Docs
API reference
Spec

Braintrust Data API v1.0.0

API specification for the backend data server. The API is hosted globally at https://api.braintrustdata.com or in your own environment. The v1 API is currently in preview mode and unstable until March 1, 2024. We may make backwards incompatible changes before then, as we learn from our users.

Base URLs:

License: Apache 2.0

Authentication

  • HTTP Authentication, scheme: bearer
    Most Braintrust endpoints are authenticated by providing your API key as a header Authorization: Bearer [api_key] to your HTTP request. You can create an API key in the Braintrust organization settings page.

Projects

Create project

Code samples
const inputBody = JSON.stringify({
  name: "string",
  org_name: "string",
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

POST /v1/project

Create a new project. If there is an existing project with the same name as the one specified in the request, will return the existing project unmodified

Body parameter
{
  "name": "string",
  "org_name": "string"
}
Parameters
NameInTypeRequiredDescription
bodybodyCreateProjecttrueAny desired information about the new project object
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "created": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the new project objectProject
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Create or replace project

Code samples
const inputBody = JSON.stringify({
  name: "string",
  org_name: "string",
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project", {
  method: "PUT",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

PUT /v1/project

Create or replace a new project. If there is an existing project with the same name as the one specified in the request, will replace the existing project with the provided fields

Body parameter
{
  "name": "string",
  "org_name": "string"
}
Parameters
NameInTypeRequiredDescription
bodybodyCreateProjecttrueAny desired information about the new project object
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "created": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the new project objectProject
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

List projects

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project", {
  method: "GET",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

GET /v1/project

List out all projects. The projects are sorted by creation date, with the most recently-created projects coming first

Parameters
NameInTypeRequiredDescription
limitqueryAppLimitParamfalseLimit the number of objects to return
starting_afterqueryStartingAfterfalsePagination cursor id.
ending_beforequeryEndingBeforefalsePagination cursor id.
project_namequeryProjectNamefalseName of the project to search for
org_namequeryOrgNamefalseFilter search results to within a particular organization
Detailed descriptions

starting_after: Pagination cursor id.

For example, if the final item in the last page you fetched had an id of foo, pass starting_after=foo to fetch the next page. Note: you may only pass one of starting_after and ending_before

ending_before: Pagination cursor id.

For example, if the initial item in the last page you fetched had an id of foo, pass ending_before=foo to fetch the previous page. Note: you may only pass one of starting_after and ending_before

Example responses

200 Response

{
  "objects": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
      "name": "string",
      "created": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
    }
  ]
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns a list of project objectsInline
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
» objects[Project]truenoneA list of project objects
»» idstring(uuid)truenoneUnique identifier for the project
»» org_idstring(uuid)truenoneUnique id for the organization that the project belongs under
»» namestringtruenoneName of the project
»» createdstring,null(date-time)falsenoneDate of project creation
»» deleted_atstring,null(date-time)falsenoneDate of project deletion, or null if the project is still active
»» user_idstring,null(uuid)falsenoneIdentifies the user who created the project
🔒
This endpoint requires authentication.

Get project

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project/{project_id}", {
  method: "GET",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

GET /v1/project/{project_id}

Get a project object by its id

Parameters
NameInTypeRequiredDescription
project_idpathProjectIdtrueProject id
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "created": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the project objectProject
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Partially update project

Code samples
const inputBody = JSON.stringify({
  name: "string",
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project/{project_id}", {
  method: "PATCH",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

PATCH /v1/project/{project_id}

Partially update a project object. Specify the fields to update in the payload. Any object-type fields will be deep-merged with existing content. Currently we do not support removing fields or setting them to null. As a workaround, you may retrieve the full object with GET /project/{id} and then replace it with PUT /project.

Body parameter
{
  "name": "string"
}
Parameters
NameInTypeRequiredDescription
project_idpathProjectIdtrueProject id
bodybodyPatchProjectfalseFields to update
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "created": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the experiment objectProject
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Delete project

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project/{project_id}", {
  method: "DELETE",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

DELETE /v1/project/{project_id}

Delete a project object by its id

Parameters
NameInTypeRequiredDescription
project_idpathProjectIdtrueProject id
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "created": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the deleted project objectProject
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Insert project logs events

Code samples
const inputBody = JSON.stringify({
  events: [
    {
      input: null,
      output: null,
      expected: null,
      scores: {
        property1: 1,
        property2: 1,
      },
      metadata: {
        property1: null,
        property2: null,
      },
      metrics: {
        start: 0,
        end: 0,
        property1: null,
        property2: null,
      },
      context: {
        caller_functionname: "string",
        caller_filename: "string",
        caller_lineno: 0,
        property1: null,
        property2: null,
      },
      span_attributes: {
        name: "string",
        type: "llm",
        property1: null,
        property2: null,
      },
      id: "string",
      _object_delete: true,
      _is_merge: false,
      _parent_id: "string",
    },
  ],
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project_logs/{project_id}/insert", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

POST /v1/project_logs/{project_id}/insert

Insert a set of events into the project logs

Body parameter
{
  "events": [
    {
      "input": null,
      "output": null,
      "expected": null,
      "scores": {
        "property1": 1,
        "property2": 1
      },
      "metadata": {
        "property1": null,
        "property2": null
      },
      "metrics": {
        "start": 0,
        "end": 0,
        "property1": null,
        "property2": null
      },
      "context": {
        "caller_functionname": "string",
        "caller_filename": "string",
        "caller_lineno": 0,
        "property1": null,
        "property2": null
      },
      "span_attributes": {
        "name": "string",
        "type": "llm",
        "property1": null,
        "property2": null
      },
      "id": "string",
      "_object_delete": true,
      "_is_merge": false,
      "_parent_id": "string"
    }
  ]
}
Parameters
NameInTypeRequiredDescription
project_idpathProjectIdtrueProject id
bodybodyInsertProjectLogsEventRequesttrueAn array of project logs events to insert
Example responses

200 Response

{
  "row_ids": ["string"]
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the inserted row idsInsertEventsResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Fetch project logs (POST form)

Code samples
const inputBody = JSON.stringify({
  limit: 0,
  max_xact_id: 0,
  max_root_span_id: "string",
  filters: [
    {
      type: "path_lookup",
      path: ["string"],
      value: null,
    },
  ],
  version: 0,
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project_logs/{project_id}/fetch", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

POST /v1/project_logs/{project_id}/fetch

Fetch the events in a project logs. Equivalent to the GET form of the same path, but with the parameters in the request body rather than in the URL query

Body parameter
{
  "limit": 0,
  "max_xact_id": 0,
  "max_root_span_id": "string",
  "filters": [
    {
      "type": "path_lookup",
      "path": ["string"],
      "value": null
    }
  ],
  "version": 0
}
Parameters
NameInTypeRequiredDescription
project_idpathProjectIdtrueProject id
bodybodyFetchEventsRequestfalseFilters for the fetch query
Example responses

200 Response

{
  "events": [
    {
      "id": "string",
      "_xact_id": 0,
      "created": "2019-08-24T14:15:22Z",
      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "log_id": "g",
      "input": null,
      "output": null,
      "expected": null,
      "scores": {
        "property1": 1,
        "property2": 1
      },
      "metadata": {
        "property1": null,
        "property2": null
      },
      "metrics": {
        "start": 0,
        "end": 0,
        "property1": null,
        "property2": null
      },
      "context": {
        "caller_functionname": "string",
        "caller_filename": "string",
        "caller_lineno": 0,
        "property1": null,
        "property2": null
      },
      "span_id": "string",
      "span_parents": ["string"],
      "root_span_id": "string",
      "span_attributes": {
        "name": "string",
        "type": "llm",
        "property1": null,
        "property2": null
      }
    }
  ]
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the fetched rowsFetchProjectLogsEventsResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Fetch project logs (GET form)

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project_logs/{project_id}/fetch", {
  method: "GET",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

GET /v1/project_logs/{project_id}/fetch

Fetch the events in a project logs. Equivalent to the POST form of the same path, but with the parameters in the URL query rather than in the request body

Parameters
NameInTypeRequiredDescription
project_idpathProjectIdtrueProject id
limitqueryFetchLimitParamfalselimit the number of traces fetched
max_xact_idqueryMaxXactIdfalseTogether, max_xact_id and max_root_span_id form a pagination cursor
max_root_span_idqueryMaxRootSpanIdfalseTogether, max_xact_id and max_root_span_id form a pagination cursor
versionqueryVersionfalseRetrieve a snapshot of events from a past time
Detailed descriptions

limit: limit the number of traces fetched

Fetch queries may be paginated if the total result size is expected to be large (e.g. project_logs which accumulate over a long time). Note that fetch queries only support pagination in descending time order (from latest to earliest _xact_id. Furthermore, later pages may return rows which showed up in earlier pages, except with an earlier _xact_id. This happens because pagination occurs over the whole version history of the event log. You will most likely want to exclude any such duplicate, outdated rows (by id) from your combined result set.

The limit parameter controls the number of full traces to return. So you may end up with more individual rows than the specified limit if you are fetching events containing traces.

max_xact_id: Together, max_xact_id and max_root_span_id form a pagination cursor

Since a paginated fetch query returns results in order from latest to earliest, the cursor for the next page can be found as the row with the minimum (earliest) value of the tuple (_xact_id, root_span_id). See the documentation of limit for an overview of paginating fetch queries.

max_root_span_id: Together, max_xact_id and max_root_span_id form a pagination cursor

Since a paginated fetch query returns results in order from latest to earliest, the cursor for the next page can be found as the row with the minimum (earliest) value of the tuple (_xact_id, root_span_id). See the documentation of limit for an overview of paginating fetch queries.

version: Retrieve a snapshot of events from a past time

The version id is essentially a filter on the latest event transaction id. You can use the max_xact_id returned by a past fetch as the version to reproduce that exact fetch.

Example responses

200 Response

{
  "events": [
    {
      "id": "string",
      "_xact_id": 0,
      "created": "2019-08-24T14:15:22Z",
      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "log_id": "g",
      "input": null,
      "output": null,
      "expected": null,
      "scores": {
        "property1": 1,
        "property2": 1
      },
      "metadata": {
        "property1": null,
        "property2": null
      },
      "metrics": {
        "start": 0,
        "end": 0,
        "property1": null,
        "property2": null
      },
      "context": {
        "caller_functionname": "string",
        "caller_filename": "string",
        "caller_lineno": 0,
        "property1": null,
        "property2": null
      },
      "span_id": "string",
      "span_parents": ["string"],
      "root_span_id": "string",
      "span_attributes": {
        "name": "string",
        "type": "llm",
        "property1": null,
        "property2": null
      }
    }
  ]
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the fetched rowsFetchProjectLogsEventsResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Feedback for project logs events

Code samples
const inputBody = JSON.stringify({
  feedback: [
    {
      id: "string",
      scores: {
        property1: 1,
        property2: 1,
      },
      expected: null,
      comment: "string",
      metadata: {
        property1: null,
        property2: null,
      },
      source: "app",
    },
  ],
});
const headers = {
  "Content-Type": "application/json",
  Accept: "text/plain",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/project_logs/{project_id}/feedback", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

POST /v1/project_logs/{project_id}/feedback

Log feedback for a set of project logs events

Body parameter
{
  "feedback": [
    {
      "id": "string",
      "scores": {
        "property1": 1,
        "property2": 1
      },
      "expected": null,
      "comment": "string",
      "metadata": {
        "property1": null,
        "property2": null
      },
      "source": "app"
    }
  ]
}
Parameters
NameInTypeRequiredDescription
project_idpathProjectIdtrueProject id
bodybodyFeedbackProjectLogsEventRequesttrueAn array of feedback objects
Example responses

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKNo return valueNone
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Experiments

Create experiment

Code samples
const inputBody = JSON.stringify({
  project_id: "405d8375-3514-403b-8c43-83ae74cfe0e9",
  name: "string",
  description: "string",
  repo_info: {
    commit: "string",
    branch: "string",
    tag: "string",
    dirty: true,
    author_name: "string",
    author_email: "string",
    commit_message: "string",
    commit_time: "string",
    git_diff: "string",
  },
  base_exp_id: "4838cee2-a665-4545-aa9f-483678c01a6b",
  dataset_id: "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  dataset_version: "string",
  public: true,
  metadata: {
    property1: null,
    property2: null,
  },
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

POST /v1/experiment

Create a new experiment. If there is an existing experiment in the project with the same name as the one specified in the request, will create a new experiment from name, suffixed with a unique identifier

Body parameter
{
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "repo_info": {
    "commit": "string",
    "branch": "string",
    "tag": "string",
    "dirty": true,
    "author_name": "string",
    "author_email": "string",
    "commit_message": "string",
    "commit_time": "string",
    "git_diff": "string"
  },
  "base_exp_id": "4838cee2-a665-4545-aa9f-483678c01a6b",
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "dataset_version": "string",
  "public": true,
  "metadata": {
    "property1": null,
    "property2": null
  }
}
Parameters
NameInTypeRequiredDescription
bodybodyCreateExperimenttrueAny desired information about the new experiment object
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "repo_info": {
    "commit": "string",
    "branch": "string",
    "tag": "string",
    "dirty": true,
    "author_name": "string",
    "author_email": "string",
    "commit_message": "string",
    "commit_time": "string",
    "git_diff": "string"
  },
  "commit": "string",
  "base_exp_id": "4838cee2-a665-4545-aa9f-483678c01a6b",
  "deleted_at": "2019-08-24T14:15:22Z",
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "dataset_version": "string",
  "public": true,
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "metadata": {
    "property1": null,
    "property2": null
  }
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the new experiment objectExperiment
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Create or replace experiment

Code samples
const inputBody = JSON.stringify({
  project_id: "405d8375-3514-403b-8c43-83ae74cfe0e9",
  name: "string",
  description: "string",
  repo_info: {
    commit: "string",
    branch: "string",
    tag: "string",
    dirty: true,
    author_name: "string",
    author_email: "string",
    commit_message: "string",
    commit_time: "string",
    git_diff: "string",
  },
  base_exp_id: "4838cee2-a665-4545-aa9f-483678c01a6b",
  dataset_id: "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  dataset_version: "string",
  public: true,
  metadata: {
    property1: null,
    property2: null,
  },
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment", {
  method: "PUT",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

PUT /v1/experiment

Create or replace a new experiment. If there is an existing experiment in the project with the same name as the one specified in the request, will replace the existing experiment with the provided fields

Body parameter
{
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "repo_info": {
    "commit": "string",
    "branch": "string",
    "tag": "string",
    "dirty": true,
    "author_name": "string",
    "author_email": "string",
    "commit_message": "string",
    "commit_time": "string",
    "git_diff": "string"
  },
  "base_exp_id": "4838cee2-a665-4545-aa9f-483678c01a6b",
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "dataset_version": "string",
  "public": true,
  "metadata": {
    "property1": null,
    "property2": null
  }
}
Parameters
NameInTypeRequiredDescription
bodybodyCreateExperimenttrueAny desired information about the new experiment object
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "repo_info": {
    "commit": "string",
    "branch": "string",
    "tag": "string",
    "dirty": true,
    "author_name": "string",
    "author_email": "string",
    "commit_message": "string",
    "commit_time": "string",
    "git_diff": "string"
  },
  "commit": "string",
  "base_exp_id": "4838cee2-a665-4545-aa9f-483678c01a6b",
  "deleted_at": "2019-08-24T14:15:22Z",
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "dataset_version": "string",
  "public": true,
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "metadata": {
    "property1": null,
    "property2": null
  }
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the new experiment objectExperiment
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

List experiments

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment", {
  method: "GET",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

GET /v1/experiment

List out all experiments. The experiments are sorted by creation date, with the most recently-created experiments coming first

Parameters
NameInTypeRequiredDescription
limitqueryAppLimitParamfalseLimit the number of objects to return
starting_afterqueryStartingAfterfalsePagination cursor id.
ending_beforequeryEndingBeforefalsePagination cursor id.
experiment_namequeryExperimentNamefalseName of the experiment to search for
project_namequeryProjectNamefalseName of the project to search for
org_namequeryOrgNamefalseFilter search results to within a particular organization
Detailed descriptions

starting_after: Pagination cursor id.

For example, if the final item in the last page you fetched had an id of foo, pass starting_after=foo to fetch the next page. Note: you may only pass one of starting_after and ending_before

ending_before: Pagination cursor id.

For example, if the initial item in the last page you fetched had an id of foo, pass ending_before=foo to fetch the previous page. Note: you may only pass one of starting_after and ending_before

Example responses

200 Response

{
  "objects": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "name": "string",
      "description": "string",
      "created": "2019-08-24T14:15:22Z",
      "repo_info": {
        "commit": "string",
        "branch": "string",
        "tag": "string",
        "dirty": true,
        "author_name": "string",
        "author_email": "string",
        "commit_message": "string",
        "commit_time": "string",
        "git_diff": "string"
      },
      "commit": "string",
      "base_exp_id": "4838cee2-a665-4545-aa9f-483678c01a6b",
      "deleted_at": "2019-08-24T14:15:22Z",
      "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
      "dataset_version": "string",
      "public": true,
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "metadata": {
        "property1": null,
        "property2": null
      }
    }
  ]
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns a list of experiment objectsInline
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
» objects[Experiment]truenoneA list of experiment objects
»» idstring(uuid)truenoneUnique identifier for the experiment
»» project_idstring(uuid)truenoneUnique identifier for the project that the experiment belongs under
»» namestringtruenoneName of the experiment. Within a project, experiment names are unique
»» descriptionstring,nullfalsenoneTextual description of the experiment
»» createdstring,null(date-time)falsenoneDate of experiment creation
»» repo_infoRepoInfofalsenoneMetadata about the state of the repo when the experiment was created
»»» commitstring,nullfalsenoneSHA of most recent commit
»»» branchstring,nullfalsenoneName of the branch the most recent commit belongs to
»»» tagstring,nullfalsenoneName of the tag on the most recent commit
»»» dirtyboolean,nullfalsenoneWhether or not the repo had uncommitted changes when snapshotted
»»» author_namestring,nullfalsenoneName of the author of the most recent commit
»»» author_emailstring,nullfalsenoneEmail of the author of the most recent commit
»»» commit_messagestring,nullfalsenoneMost recent commit message
»»» commit_timestring,nullfalsenoneTime of the most recent commit
»»» git_diffstring,nullfalsenoneIf the repo was dirty when run, this includes the diff between the current state of the repo and the most recent commit.
»» commitstring,nullfalsenoneCommit, taken directly from repo_info.commit
»» base_exp_idstring,null(uuid)falsenoneId of default base experiment to compare against when viewing this experiment
»» deleted_atstring,null(date-time)falsenoneDate of experiment deletion, or null if the experiment is still active
»» dataset_idstring,null(uuid)falsenoneIdentifier of the linked dataset, or null if the experiment is not linked to a dataset
»» dataset_versionstring,nullfalsenoneVersion number of the linked dataset the experiment was run against. This can be used to reproduce the experiment after the dataset has been modified.
»» publicbooleantruenoneWhether or not the experiment is public. Public experiments can be viewed by anybody inside or outside the organization
»» user_idstring,null(uuid)falsenoneIdentifies the user who created the experiment
»» metadataobject,nullfalsenoneUser-controlled metadata about the experiment
»»» additionalPropertiesanyfalsenonenone
🔒
This endpoint requires authentication.

Get experiment

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment/{experiment_id}", {
  method: "GET",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

GET /v1/experiment/{experiment_id}

Get an experiment object by its id

Parameters
NameInTypeRequiredDescription
experiment_idpathExperimentIdtrueExperiment id
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "repo_info": {
    "commit": "string",
    "branch": "string",
    "tag": "string",
    "dirty": true,
    "author_name": "string",
    "author_email": "string",
    "commit_message": "string",
    "commit_time": "string",
    "git_diff": "string"
  },
  "commit": "string",
  "base_exp_id": "4838cee2-a665-4545-aa9f-483678c01a6b",
  "deleted_at": "2019-08-24T14:15:22Z",
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "dataset_version": "string",
  "public": true,
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "metadata": {
    "property1": null,
    "property2": null
  }
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the experiment objectExperiment
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Partially update experiment

Code samples
const inputBody = JSON.stringify({
  name: "string",
  description: "string",
  repo_info: {
    commit: "string",
    branch: "string",
    tag: "string",
    dirty: true,
    author_name: "string",
    author_email: "string",
    commit_message: "string",
    commit_time: "string",
    git_diff: "string",
  },
  base_exp_id: "4838cee2-a665-4545-aa9f-483678c01a6b",
  dataset_id: "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  dataset_version: "string",
  public: true,
  metadata: {
    property1: null,
    property2: null,
  },
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment/{experiment_id}", {
  method: "PATCH",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

PATCH /v1/experiment/{experiment_id}

Partially update an experiment object. Specify the fields to update in the payload. Any object-type fields will be deep-merged with existing content. Currently we do not support removing fields or setting them to null. As a workaround, you may retrieve the full object with GET /experiment/{id} and then replace it with PUT /experiment.

Body parameter
{
  "name": "string",
  "description": "string",
  "repo_info": {
    "commit": "string",
    "branch": "string",
    "tag": "string",
    "dirty": true,
    "author_name": "string",
    "author_email": "string",
    "commit_message": "string",
    "commit_time": "string",
    "git_diff": "string"
  },
  "base_exp_id": "4838cee2-a665-4545-aa9f-483678c01a6b",
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "dataset_version": "string",
  "public": true,
  "metadata": {
    "property1": null,
    "property2": null
  }
}
Parameters
NameInTypeRequiredDescription
experiment_idpathExperimentIdtrueExperiment id
bodybodyPatchExperimentfalseFields to update
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "repo_info": {
    "commit": "string",
    "branch": "string",
    "tag": "string",
    "dirty": true,
    "author_name": "string",
    "author_email": "string",
    "commit_message": "string",
    "commit_time": "string",
    "git_diff": "string"
  },
  "commit": "string",
  "base_exp_id": "4838cee2-a665-4545-aa9f-483678c01a6b",
  "deleted_at": "2019-08-24T14:15:22Z",
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "dataset_version": "string",
  "public": true,
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "metadata": {
    "property1": null,
    "property2": null
  }
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the experiment objectExperiment
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Delete experiment

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment/{experiment_id}", {
  method: "DELETE",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

DELETE /v1/experiment/{experiment_id}

Delete an experiment object by its id

Parameters
NameInTypeRequiredDescription
experiment_idpathExperimentIdtrueExperiment id
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "repo_info": {
    "commit": "string",
    "branch": "string",
    "tag": "string",
    "dirty": true,
    "author_name": "string",
    "author_email": "string",
    "commit_message": "string",
    "commit_time": "string",
    "git_diff": "string"
  },
  "commit": "string",
  "base_exp_id": "4838cee2-a665-4545-aa9f-483678c01a6b",
  "deleted_at": "2019-08-24T14:15:22Z",
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "dataset_version": "string",
  "public": true,
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "metadata": {
    "property1": null,
    "property2": null
  }
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the deleted experiment objectExperiment
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Insert experiment events

Code samples
const inputBody = JSON.stringify({
  events: [
    {
      input: null,
      output: null,
      expected: null,
      scores: {
        property1: 1,
        property2: 1,
      },
      metadata: {
        property1: null,
        property2: null,
      },
      metrics: {
        start: 0,
        end: 0,
        property1: null,
        property2: null,
      },
      context: {
        caller_functionname: "string",
        caller_filename: "string",
        caller_lineno: 0,
        property1: null,
        property2: null,
      },
      span_attributes: {
        name: "string",
        type: "llm",
        property1: null,
        property2: null,
      },
      id: "string",
      dataset_record_id: "string",
      _object_delete: true,
      _is_merge: false,
      _parent_id: "string",
    },
  ],
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment/{experiment_id}/insert", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

POST /v1/experiment/{experiment_id}/insert

Insert a set of events into the experiment

Body parameter
{
  "events": [
    {
      "input": null,
      "output": null,
      "expected": null,
      "scores": {
        "property1": 1,
        "property2": 1
      },
      "metadata": {
        "property1": null,
        "property2": null
      },
      "metrics": {
        "start": 0,
        "end": 0,
        "property1": null,
        "property2": null
      },
      "context": {
        "caller_functionname": "string",
        "caller_filename": "string",
        "caller_lineno": 0,
        "property1": null,
        "property2": null
      },
      "span_attributes": {
        "name": "string",
        "type": "llm",
        "property1": null,
        "property2": null
      },
      "id": "string",
      "dataset_record_id": "string",
      "_object_delete": true,
      "_is_merge": false,
      "_parent_id": "string"
    }
  ]
}
Parameters
NameInTypeRequiredDescription
experiment_idpathExperimentIdtrueExperiment id
bodybodyInsertExperimentEventRequesttrueAn array of experiment events to insert
Example responses

200 Response

{
  "row_ids": ["string"]
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the inserted row idsInsertEventsResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Fetch experiment (POST form)

Code samples
const inputBody = JSON.stringify({
  limit: 0,
  max_xact_id: 0,
  max_root_span_id: "string",
  filters: [
    {
      type: "path_lookup",
      path: ["string"],
      value: null,
    },
  ],
  version: 0,
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment/{experiment_id}/fetch", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

POST /v1/experiment/{experiment_id}/fetch

Fetch the events in an experiment. Equivalent to the GET form of the same path, but with the parameters in the request body rather than in the URL query

Body parameter
{
  "limit": 0,
  "max_xact_id": 0,
  "max_root_span_id": "string",
  "filters": [
    {
      "type": "path_lookup",
      "path": ["string"],
      "value": null
    }
  ],
  "version": 0
}
Parameters
NameInTypeRequiredDescription
experiment_idpathExperimentIdtrueExperiment id
bodybodyFetchEventsRequestfalseFilters for the fetch query
Example responses

200 Response

{
  "events": [
    {
      "id": "string",
      "dataset_record_id": "string",
      "_xact_id": 0,
      "created": "2019-08-24T14:15:22Z",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "experiment_id": "916afd89-cac5-4339-9c59-dd068abdfa69",
      "input": null,
      "output": null,
      "expected": null,
      "scores": {
        "property1": 1,
        "property2": 1
      },
      "metadata": {
        "property1": null,
        "property2": null
      },
      "metrics": {
        "start": 0,
        "end": 0,
        "property1": null,
        "property2": null
      },
      "context": {
        "caller_functionname": "string",
        "caller_filename": "string",
        "caller_lineno": 0,
        "property1": null,
        "property2": null
      },
      "span_id": "string",
      "span_parents": ["string"],
      "root_span_id": "string",
      "span_attributes": {
        "name": "string",
        "type": "llm",
        "property1": null,
        "property2": null
      }
    }
  ]
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the fetched rowsFetchExperimentEventsResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Fetch experiment (GET form)

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment/{experiment_id}/fetch", {
  method: "GET",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

GET /v1/experiment/{experiment_id}/fetch

Fetch the events in an experiment. Equivalent to the POST form of the same path, but with the parameters in the URL query rather than in the request body

Parameters
NameInTypeRequiredDescription
experiment_idpathExperimentIdtrueExperiment id
limitqueryFetchLimitParamfalselimit the number of traces fetched
max_xact_idqueryMaxXactIdfalseTogether, max_xact_id and max_root_span_id form a pagination cursor
max_root_span_idqueryMaxRootSpanIdfalseTogether, max_xact_id and max_root_span_id form a pagination cursor
versionqueryVersionfalseRetrieve a snapshot of events from a past time
Detailed descriptions

limit: limit the number of traces fetched

Fetch queries may be paginated if the total result size is expected to be large (e.g. project_logs which accumulate over a long time). Note that fetch queries only support pagination in descending time order (from latest to earliest _xact_id. Furthermore, later pages may return rows which showed up in earlier pages, except with an earlier _xact_id. This happens because pagination occurs over the whole version history of the event log. You will most likely want to exclude any such duplicate, outdated rows (by id) from your combined result set.

The limit parameter controls the number of full traces to return. So you may end up with more individual rows than the specified limit if you are fetching events containing traces.

max_xact_id: Together, max_xact_id and max_root_span_id form a pagination cursor

Since a paginated fetch query returns results in order from latest to earliest, the cursor for the next page can be found as the row with the minimum (earliest) value of the tuple (_xact_id, root_span_id). See the documentation of limit for an overview of paginating fetch queries.

max_root_span_id: Together, max_xact_id and max_root_span_id form a pagination cursor

Since a paginated fetch query returns results in order from latest to earliest, the cursor for the next page can be found as the row with the minimum (earliest) value of the tuple (_xact_id, root_span_id). See the documentation of limit for an overview of paginating fetch queries.

version: Retrieve a snapshot of events from a past time

The version id is essentially a filter on the latest event transaction id. You can use the max_xact_id returned by a past fetch as the version to reproduce that exact fetch.

Example responses

200 Response

{
  "events": [
    {
      "id": "string",
      "dataset_record_id": "string",
      "_xact_id": 0,
      "created": "2019-08-24T14:15:22Z",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "experiment_id": "916afd89-cac5-4339-9c59-dd068abdfa69",
      "input": null,
      "output": null,
      "expected": null,
      "scores": {
        "property1": 1,
        "property2": 1
      },
      "metadata": {
        "property1": null,
        "property2": null
      },
      "metrics": {
        "start": 0,
        "end": 0,
        "property1": null,
        "property2": null
      },
      "context": {
        "caller_functionname": "string",
        "caller_filename": "string",
        "caller_lineno": 0,
        "property1": null,
        "property2": null
      },
      "span_id": "string",
      "span_parents": ["string"],
      "root_span_id": "string",
      "span_attributes": {
        "name": "string",
        "type": "llm",
        "property1": null,
        "property2": null
      }
    }
  ]
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the fetched rowsFetchExperimentEventsResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Feedback for experiment events

Code samples
const inputBody = JSON.stringify({
  feedback: [
    {
      id: "string",
      scores: {
        property1: 1,
        property2: 1,
      },
      expected: null,
      comment: "string",
      metadata: {
        property1: null,
        property2: null,
      },
      source: "app",
    },
  ],
});
const headers = {
  "Content-Type": "application/json",
  Accept: "text/plain",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/experiment/{experiment_id}/feedback", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

POST /v1/experiment/{experiment_id}/feedback

Log feedback for a set of experiment events

Body parameter
{
  "feedback": [
    {
      "id": "string",
      "scores": {
        "property1": 1,
        "property2": 1
      },
      "expected": null,
      "comment": "string",
      "metadata": {
        "property1": null,
        "property2": null
      },
      "source": "app"
    }
  ]
}
Parameters
NameInTypeRequiredDescription
experiment_idpathExperimentIdtrueExperiment id
bodybodyFeedbackExperimentEventRequesttrueAn array of feedback objects
Example responses

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKNo return valueNone
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Summarize experiment

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch(
  "https://api.braintrustdata.com/v1/experiment/{experiment_id}/summarize",
  {
    method: "GET",
 
    headers: headers,
  },
)
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

GET /v1/experiment/{experiment_id}/summarize

Summarize experiment

Parameters
NameInTypeRequiredDescription
experiment_idpathExperimentIdtrueExperiment id
summarize_scoresquerySummarizeScoresfalseWhether to summarize the scores and metrics. If false (or omitted), only the metadata will be returned.
comparison_experiment_idqueryComparisonExperimentIdfalseThe experiment to compare against, if summarizing scores and metrics. If omitted, will fall back to the base_exp_id stored in the experiment metadata, and then to the most recent experiment run in the same project. Must pass summarize_scores=true for this id to be used
Example responses

200 Response

{
  "project_name": "string",
  "experiment_name": "string",
  "project_url": "http://example.com",
  "experiment_url": "http://example.com",
  "comparison_experiment_name": "string",
  "scores": {
    "property1": {
      "name": "string",
      "score": 1,
      "diff": -1,
      "improvements": 0,
      "regressions": 0
    },
    "property2": {
      "name": "string",
      "score": 1,
      "diff": -1,
      "improvements": 0,
      "regressions": 0
    }
  },
  "metrics": {
    "property1": {
      "name": "string",
      "metric": 0,
      "unit": "string",
      "diff": 0,
      "improvements": 0,
      "regressions": 0
    },
    "property2": {
      "name": "string",
      "metric": 0,
      "unit": "string",
      "diff": 0,
      "improvements": 0,
      "regressions": 0
    }
  }
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKexperiment summarySummarizeExperimentResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Datasets

Create dataset

Code samples
const inputBody = JSON.stringify({
  project_id: "405d8375-3514-403b-8c43-83ae74cfe0e9",
  name: "string",
  description: "string",
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/dataset", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

POST /v1/dataset

Create a new dataset. If there is an existing dataset in the project with the same name as the one specified in the request, will return the existing dataset unmodified

Body parameter
{
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string"
}
Parameters
NameInTypeRequiredDescription
bodybodyCreateDatasettrueAny desired information about the new dataset object
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the new dataset objectDataset
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Create or replace dataset

Code samples
const inputBody = JSON.stringify({
  project_id: "405d8375-3514-403b-8c43-83ae74cfe0e9",
  name: "string",
  description: "string",
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/dataset", {
  method: "PUT",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

PUT /v1/dataset

Create or replace a new dataset. If there is an existing dataset in the project with the same name as the one specified in the request, will replace the existing dataset with the provided fields

Body parameter
{
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string"
}
Parameters
NameInTypeRequiredDescription
bodybodyCreateDatasettrueAny desired information about the new dataset object
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the new dataset objectDataset
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

List datasets

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/dataset", {
  method: "GET",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

GET /v1/dataset

List out all datasets. The datasets are sorted by creation date, with the most recently-created datasets coming first

Parameters
NameInTypeRequiredDescription
limitqueryAppLimitParamfalseLimit the number of objects to return
starting_afterqueryStartingAfterfalsePagination cursor id.
ending_beforequeryEndingBeforefalsePagination cursor id.
dataset_namequeryDatasetNamefalseName of the dataset to search for
project_namequeryProjectNamefalseName of the project to search for
org_namequeryOrgNamefalseFilter search results to within a particular organization
Detailed descriptions

starting_after: Pagination cursor id.

For example, if the final item in the last page you fetched had an id of foo, pass starting_after=foo to fetch the next page. Note: you may only pass one of starting_after and ending_before

ending_before: Pagination cursor id.

For example, if the initial item in the last page you fetched had an id of foo, pass ending_before=foo to fetch the previous page. Note: you may only pass one of starting_after and ending_before

Example responses

200 Response

{
  "objects": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "name": "string",
      "description": "string",
      "created": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
    }
  ]
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns a list of dataset objectsInline
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
» objects[Dataset]truenoneA list of dataset objects
»» idstring(uuid)truenoneUnique identifier for the dataset
»» project_idstring,null(uuid)falsenoneUnique identifier for the project that the dataset belongs under
»» namestringtruenoneName of the dataset. Within a project, dataset names are unique
»» descriptionstring,nullfalsenoneTextual description of the dataset
»» createdstring,null(date-time)falsenoneDate of dataset creation
»» deleted_atstring,null(date-time)falsenoneDate of dataset deletion, or null if the dataset is still active
»» user_idstring,null(uuid)falsenoneIdentifies the user who created the dataset
🔒
This endpoint requires authentication.

Get dataset

Code samples
const headers = {
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/dataset/{dataset_id}", {
  method: "GET",
 
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

GET /v1/dataset/{dataset_id}

Get a dataset object by its id

Parameters
NameInTypeRequiredDescription
dataset_idpathDatasetIdtrueDataset id
Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the dataset objectDataset
400Bad RequestThe request was unacceptable, often due to missing a required parameterstring
401UnauthorizedNo valid API key providedstring
403ForbiddenThe API key doesn’t have permissions to perform the requeststring
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)string
🔒
This endpoint requires authentication.

Partially update dataset

Code samples
const inputBody = JSON.stringify({
  name: "string",
  description: "string",
});
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: "Bearer {access-token}",
};
 
fetch("https://api.braintrustdata.com/v1/dataset/{dataset_id}", {
  method: "PATCH",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

PATCH /v1/dataset/{dataset_id}

Partially update a dataset object. Specify the fields to update in the payload. Any object-type fields will be deep-merged with existing content. Currently we do not support removing fields or setting them to null. As a workaround, you may retrieve the full object with GET /dataset/{id} and then replace it with PUT /dataset.

Body parameter
{
  "name": "string",
  "description": "string"
}
Parameters
NameInTypeRequiredDescription
dataset_idpathDatasetIdtrueDataset id