Braintest
POST/v1/dataset/{dataset_id}/fetch

Fetch dataset (POST form)

Fetch the events in a dataset. Equivalent to the GET form of the same path, but with the parameters in the request body rather than in the URL query. For more complex queries, use the POST /btql endpoint.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 5 body fields
dataset_idstringrequired
Dataset id

Filters for the fetch query

limitintegeroptional
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.
cursorstringoptional
An opaque string to be used as a cursor for the next page of results, in order from latest to earliest. The string can be obtained directly from the `cursor` property of the previous fetch query
max_xact_idstringoptional
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_idstringoptional
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.
versionstringoptional
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.

6 status codes
200Returns the fetched rows
eventsarray<object>required
A list of fetched events
cursorstringoptional
Pagination cursor Pass this string directly as the `cursor` param to your next fetch request to get the next page of results. Not provided if the returned result set is empty.
400The request was unacceptable, often due to missing a required parameter
401No valid API key provided
403The API key doesn’t have permissions to perform the request
429Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
500Something went wrong on Braintrust's end. (These are rare.)

Error handling

A 400 is returned: The request was unacceptable, often due to missing a required parameter A 401 is returned: No valid API key provided A 403 is returned: The API key doesn’t have permissions to perform the request A 429 is returned: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests A 500 is returned: Something went wrong on Braintrust's end. (These are rare.)