Docs
Reference
API

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 June 1, 2024. We may make backwards incompatible changes before then, as we learn from our users.

You can access the OpenAPI spec for this API at https://github.com/braintrustdata/braintrust-openapi.

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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
This endpoint requires authentication.

DEPRECATED. 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

NOTE: This operation is deprecated and will be removed in a future revision of the API. Create or replace 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, 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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline

Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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
idsqueryIdsfalseFilter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
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(date-time)¦nullfalsenoneDate of project creation
»» deleted_atstring(date-time)¦nullfalsenoneDate of project deletion, or null if the project is still active
»» user_idstring(uuid)¦nullfalsenoneIdentifies the user who created the project

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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.

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 project objectProject
400Bad RequestThe request was unacceptable, often due to missing a required parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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,
      },
      tags: ["string"],
      metrics: {
        start: 0,
        end: 0,
        prompt_tokens: 0,
        completion_tokens: 0,
        tokens: 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
      },
      "tags": ["string"],
      "metrics": {
        "start": 0,
        "end": 0,
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "tokens": 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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
This endpoint requires authentication.

Fetch project logs (POST form)

Code samples
const inputBody = JSON.stringify({
  limit: 0,
  cursor: "string",
  max_xact_id: "string",
  max_root_span_id: "string",
  filters: [
    {
      type: "path_lookup",
      path: ["string"],
      value: null,
    },
  ],
  version: "string",
});
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,
  "cursor": "string",
  "max_xact_id": "string",
  "max_root_span_id": "string",
  "filters": [
    {
      "type": "path_lookup",
      "path": ["string"],
      "value": null
    }
  ],
  "version": "string"
}
Parameters
NameInTypeRequiredDescription
project_idpathProjectIdtrueProject id
bodybodyFetchEventsRequestfalseFilters for the fetch query
Example responses

200 Response

{
  "events": [
    {
      "id": "string",
      "_xact_id": "string",
      "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
      },
      "tags": ["string"],
      "metrics": {
        "start": 0,
        "end": 0,
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "tokens": 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
      }
    }
  ],
  "cursor": "string"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the fetched rowsFetchProjectLogsEventsResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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_idqueryMaxXactIdfalseDEPRECATION NOTICE: The manually-constructed pagination cursor is deprecated in favor of the explicit 'cursor' returned by object fetch requests. Please prefer the 'cursor' argument going forwards.
max_root_span_idqueryMaxRootSpanIdfalseDEPRECATION NOTICE: The manually-constructed pagination cursor is deprecated in favor of the explicit 'cursor' returned by object fetch requests. Please prefer the 'cursor' argument going forwards.
versionqueryanyfalseRetrieve prompt at a specific version.
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: DEPRECATION NOTICE: The manually-constructed pagination cursor is deprecated in favor of the explicit 'cursor' returned by object fetch requests. Please prefer the 'cursor' argument going forwards.

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: DEPRECATION NOTICE: The manually-constructed pagination cursor is deprecated in favor of the explicit 'cursor' returned by object fetch requests. Please prefer the 'cursor' argument going forwards.

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 prompt at a specific version.

The version id can either be a transaction id (e.g. '1000192656880881099') or a version identifier (e.g. '81cd05ee665fdfb3').

Example responses

200 Response

{
  "events": [
    {
      "id": "string",
      "_xact_id": "string",
      "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
      },
      "tags": ["string"],
      "metrics": {
        "start": 0,
        "end": 0,
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "tokens": 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
      }
    }
  ],
  "cursor": "string"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the fetched rowsFetchProjectLogsEventsResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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"
null
Responses
StatusMeaningDescriptionSchema
200OKNo return valueNone
400Bad RequestThe request was unacceptable, often due to missing a required parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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,
  },
  ensure_new: true,
});
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 return the existing experiment unmodified

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
  },
  "ensure_new": true
}
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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
This endpoint requires authentication.

DEPRECATED. 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,
  },
  ensure_new: true,
});
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

NOTE: This operation is deprecated and will be removed in a future revision of the API. 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 return the existing experiment unmodified, 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
  },
  "ensure_new": true
}
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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline

Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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
idsqueryIdsfalseFilter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
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(date-time)¦nullfalsenoneDate of experiment creation
»» repo_infoRepoInfo¦nullfalsenoneMetadata 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(uuid)¦nullfalsenoneId of default base experiment to compare against when viewing this experiment
»» deleted_atstring(date-time)¦nullfalsenoneDate of experiment deletion, or null if the experiment is still active
»» dataset_idstring(uuid)¦nullfalsenoneIdentifier 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(uuid)¦nullfalsenoneIdentifies the user who created the experiment
»» metadataobject¦nullfalsenoneUser-controlled metadata about the experiment
»»» additionalPropertiesanyfalsenonenone

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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.

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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
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,
      },
      tags: ["string"],
      metrics: {
        start: 0,
        end: 0,
        prompt_tokens: 0,
        completion_tokens: 0,
        tokens: 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
      },
      "tags": ["string"],
      "metrics": {
        "start": 0,
        "end": 0,
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "tokens": 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 parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requestsInline
500Internal Server ErrorSomething went wrong on Braintrust's end. (These are rare.)Inline
Response Schema

Status Code 400

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 401

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 403

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 429

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone

Status Code 500

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenonenone
🔒
This endpoint requires authentication.

Fetch experiment (POST form)

Code samples
const inputBody = JSON.stringify({
  limit: 0,
  cursor: "string",
  max_xact_id: "string",
  max_root_span_id: "string",
  filters: [
    {
      type: "path_lookup",
      path: ["string"],
      value: null,
    },
  ],
  version: "string",
});
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,
  "cursor": "string",
  "max_xact_id": "string",
  "max_root_span_id": "string",
  "filters": [
    {
      "type": "path_lookup",
      "path": ["string"],
      "value": null
    }
  ],
  "version": "string"
}
Parameters
NameInTypeRequiredDescription
experiment_idpathExperimentIdtrueExperiment id
bodybodyFetchEventsRequestfalseFilters for the fetch query
Example responses

200 Response

{
  "events": [
    {
      "id": "string",
      "dataset_record_id": "string",
      "_xact_id": "string",
      "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
      },
      "tags": ["string"],
      "metrics": {
        "start": 0,
        "end": 0,
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "tokens": 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
      }
    }
  ],
  "cursor": "string"
}

400 Response

"string"
Responses
StatusMeaningDescriptionSchema
200OKReturns the fetched rowsFetchExperimentEventsResponse
400Bad RequestThe request was unacceptable, often due to missing a required parameterInline
401UnauthorizedNo valid API key providedInline
403ForbiddenThe API key doesn’t have permissions to perform the requestInline
429Too Many RequestsToo many requests hit the API too quickly. We recommend a