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.

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

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

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

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

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"
          }
        }
      ]
    }
  ]
}