Traces

Programmatically interact with your Autoblocks traces.

POSThttps://api.autoblocks.ai/traces/search

Search traces

This endpoint allows you to search and paginate through traces. Traces are returned in descending order based on the trace's starting timestamp, and within a trace, events are in ascending order based on the event's timestamp. The nextCursor property returned in the response can be used to get the next page of traces. When there are no more traces, nextCursor will not be defined.

Request body

Name
pageSize
Type
number (required)
Description
How many traces to return per page. Must be an integer between 1 and 100.
Name
cursor
Type
string
Description
Optional field used for paginating through traces. This should be set to the nextCursor field returned from the previous request.
The cursor argument you pass is only valid if you are sending the same request body as the request where you got the nextCursor from.
Name
timeFilter
Type
object (required)
Description
Either a relative or absolute time filter.
Absolute:
Name
type
Type
string (required)
Description
The type of time filter. Must be the string "absolute".
Name
start
Type
string (required)
Description
The start time as an ISO 8601 timestamp (inclusive).
Name
end
Type
string (required)
Description
The end time as an ISO 8601 timestamp (inclusive).
Relative:
Name
type
Type
string (required)
Description
The type of time filter. Must be the string "relative".
Name
seconds
Type
number
Description
The number of seconds since now.
Name
minutes
Type
number
Description
The number of minutes since now.
Name
hours
Type
number
Description
The number of hours since now.
Name
days
Type
number
Description
The number of days since now.
Name
weeks
Type
number
Description
The number of weeks since now.
Name
months
Type
number
Description
The number of months since now.
Name
years
Type
number
Description
The number of years since now.
You can use any combination of the above fields to express a relative time filter.
For example:
{"hours": 1, "minutes": 30}
Is the same as:
{"hours": 1.5}
Name
traceFilters
Type
object[]
Description
A list of trace filters.
Name
operator
Type
string
Description
Must be one of:

'CONTAINS': search for traces that contain at least one event that matches the event filters

'NOT_CONTAINS': search for traces that do not contain any events that match the event filters
Name
eventFilters
Type
object[]
Description
A list of event filters.
Name
key
Type
string
Description
The name of the event property.
If you want to filter on an event's message or label, use these special keys:

To filter on message: SYSTEM:message

To filter on labels: SYSTEM:label

Name
operator
Type
string
Description
Must be one of:

'CONTAINS': properties[key] ILIKE %value%

'NOT_CONTAINS': properties[key] NOT ILIKE %value%

'EQUALS': properties[key] == value

'NOT_EQUALS': properties[key] != value

'LESS_THAN': properties[key] < value

'LESS_THAN_OR_EQUALS': properties[key] <= value

'GREATER_THAN': properties[key] > value

'GREATER_THAN_OR_EQUALS': properties[key] >= value

Name
value
Type
string
Description
The value to search for.
If you are searching for a label, use the label's ID as the value. You can find the label ID on the labels page.
Go to labels page

Code samples for searching traces

POST

https://api.autoblocks.ai/traces/search

curl -X POST 'https://api.autoblocks.ai/traces/search' \
  --header "Authorization: Bearer $AUTOBLOCKS_API_KEY" \
  --data '{
    "pageSize": 10,
    "timeFilter": {
      "type": "relative",
      "hours": 1
    },
    "traceFilters": [
      {
        "operator": "CONTAINS",
        "eventFilters": [
          {
            key: "SYSTEM:message",
            operator: "EQUALS",
            value: "model.input"
          },
          {
            key: "input",
            operator: "CONTAINS",
            value: "poem"
          }
        ]
      }
    ]
  }'

{
  "nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDIzLTAxLTAxVDAwOjAwOjAxLjEyM1oiLCJldmVudElkIjoiZXZlbnQtMSJ9",
  "traces": [
    {
      "id": "57dea9fe-b2ab-44ad-853e-d09a207de6e3",
      "events": [
        {
          "id": "97587dfa-e0ef-4d9b-b73b-4088584cec1e",
          "traceId": "57dea9fe-b2ab-44ad-853e-d09a207de6e3",
          "timestamp": "2021-04-08T18:00:00.000Z",
          "message": "model.input",
          "properties": {
            "input": "Write me a poem"
          }
        }
      ]
    }
  ]
}

Example: Search for presence of multiple events

Find traces that occurred within the last hour that contain both:

at least one event where the message is "model.input" and the input property contains the string "poem"
at least one event where the message is "user.feedback" and the feedback property equals "negative"

Code samples

POST

https://api.autoblocks.ai/traces/search

curl -X POST 'https://api.autoblocks.ai/traces/search' \
  --header "Authorization: Bearer $AUTOBLOCKS_API_KEY" \
  --data '{
    "pageSize": 10,
    "timeFilter": {
      "type": "relative",
      "hours": 1
    },
    "traceFilters": [
      {
        "operator": "CONTAINS",
        "eventFilters": [
          {
            key: "SYSTEM:message",
            operator: "EQUALS",
            value: "model.input"
          },
          {
            key: "input",
            operator: "CONTAINS",
            value: "poem"
          }
        ]
      },
      {
        "operator": "CONTAINS",
        "eventFilters": [
          {
            key: "SYSTEM:message",
            operator: "EQUALS",
            value: "user.feedback"
          },
          {
            key: "feedback",
            operator: "EQUALS",
            value: "negative"
          }
        ]
      }
    ]
  }'

Example response

{
  "nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDIzLTAxLTAxVDAwOjAwOjAxLjEyM1oiLCJldmVudElkIjoiZXZlbnQtMSJ9",
  "traces": [
    {
      "id": "b43b0df0-b0de-4948-a655-03594d123516",
      "events": [
        {
          "id": "f8e9da81-06c5-46cb-bd2d-08067ca078e0",
          "traceId": "b43b0df0-b0de-4948-a655-03594d123516",
          "timestamp": "2021-04-08T18:00:00.000Z",
          "message": "model.input",
          "properties": {
            "input": "Write me a poem"
          }
        },
        // other events ...
        {
          "id": "b05b2751-77ea-4941-aac1-34d7cbb959a7",
          "traceId": "b43b0df0-b0de-4948-a655-03594d123516",
          "timestamp": "2021-04-08T18:01:00.000Z",
          "message": "user.feedback",
          "properties": {
            "feedback": "negative"
          }
        }
      ]
    }
  ]
}

Example: Search for absence of event

Find traces that occurred within the last hour that:

contain at least one event where the message is "model.input" and the input property contains the string "poem"
do not contain any events where the message is "user.feedback"

Code samples

POST

https://api.autoblocks.ai/traces/search

curl -X POST 'https://api.autoblocks.ai/traces/search' \
  --header "Authorization: Bearer $AUTOBLOCKS_API_KEY" \
  --data '{
    "pageSize": 10,
    "timeFilter": {
      "type": "relative",
      "hours": 1
    },
    "traceFilters": [
      {
        "operator": "CONTAINS",
        "eventFilters": [
          {
            key: "SYSTEM:message",
            operator: "EQUALS",
            value: "model.input"
          },
          {
            key: "input",
            operator: "CONTAINS",
            value: "poem"
          }
        ]
      },
      {
        "operator": "NOT_CONTAINS",
        "eventFilters": [
          {
            key: "SYSTEM:message",
            operator: "EQUALS",
            value: "user.feedback"
          }
        ]
      }
    ]
  }'

Example response

{
  "nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDIzLTAxLTAxVDAwOjAwOjAxLjEyM1oiLCJldmVudElkIjoiZXZlbnQtMSJ9",
  "traces": [
    {
      "id": "57dea9fe-b2ab-44ad-853e-d09a207de6e3",
      "events": [
        {
          "id": "97587dfa-e0ef-4d9b-b73b-4088584cec1e",
          "traceId": "57dea9fe-b2ab-44ad-853e-d09a207de6e3",
          "timestamp": "2021-04-08T18:00:00.000Z",
          "message": "model.input",
          "properties": {
            "input": "Write me a poem"
          }
        }
        // other events ...
        // no user.feedback event
      ]
    }
  ]
}

Example: Search by label

If you are searching for a label, use the label's ID as the value. You can find the label ID on the labels page.

Go to labels page

Code samples

POST

https://api.autoblocks.ai/traces/search

curl -X POST 'https://api.autoblocks.ai/traces/search' \
  --header "Authorization: Bearer $AUTOBLOCKS_API_KEY" \
  --data '{
    "pageSize": 10,
    "timeFilter": {
      "type": "relative",
      "hours": 1
    },
    "traceFilters": [
      {
        "operator": "CONTAINS",
        "eventFilters": [
          {
            key: "SYSTEM:label",
            operator: "EQUALS",
            value: "cllmhfrrj0000q5php84hn6os"
          }
        ]
      }
    ]
  }'

Example response

{
  "nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDIzLTAxLTAxVDAwOjAwOjAxLjEyM1oiLCJldmVudElkIjoiZXZlbnQtMSJ9",
  "traces": [
    {
      "id": "57dea9fe-b2ab-44ad-853e-d09a207de6e3",
      "events": [
        {
          "id": "97587dfa-e0ef-4d9b-b73b-4088584cec1e",
          "traceId": "57dea9fe-b2ab-44ad-853e-d09a207de6e3",
          "timestamp": "2021-04-08T18:00:00.000Z",
          "message": "model.input",
          "properties": {
            "input": "Write me a poem"
          }
        }
      ]
    }
  ]
}