Query traces | Runtype Documentation

{
  "data": {
    "groupBy": [
      "agent"
    ],
    "groups": [
      {
        "cost": {
          "p50": 1.1,
          "p95": 1.1,
          "pricedRuns": 1.1,
          "sum": 1.1,
          "unpricedRuns": 1.1
        },
        "count": 1.1,
        "durationMs": {
          "p50": 1.1,
          "p95": 1.1
        },
        "failed": 1.1,
        "failureRate": 1.1,
        "key": {},
        "sampleExecutionIds": [
          "string"
        ],
        "tokens": {
          "p50": 1.1,
          "p95": 1.1,
          "reportedRuns": 1.1,
          "sum": 1.1
        },
        "toolCalls": {
          "p50": 1.1,
          "p95": 1.1
        },
        "signalRate": {
          "filtered": {
            "evaluated": 1.1,
            "fired": 1.1,
            "rate": 1.1
          },
          "uniform": {
            "evaluated": 1.1,
            "fired": 1.1,
            "rate": 1.1
          }
        }
      }
    ],
    "nextCursor": "string",
    "totals": {
      "cost": {
        "p50": 1.1,
        "p95": 1.1,
        "pricedRuns": 1.1,
        "sum": 1.1,
        "unpricedRuns": 1.1
      },
      "count": 1.1,
      "durationMs": {
        "p50": 1.1,
        "p95": 1.1
      },
      "failed": 1.1,
      "failureRate": 1.1,
      "tokens": {
        "p50": 1.1,
        "p95": 1.1,
        "reportedRuns": 1.1,
        "sum": 1.1
      },
      "toolCalls": {
        "p50": 1.1,
        "p95": 1.1
      },
      "signalRate": {
        "filtered": {
          "evaluated": 1.1,
          "fired": 1.1,
          "rate": 1.1
        },
        "uniform": {
          "evaluated": 1.1,
          "fired": 1.1,
          "rate": 1.1
        }
      }
    },
    "truncated": true,
    "warnings": [
      {
        "code": "string",
        "message": "string"
      }
    ],
    "window": {
      "from": "string",
      "to": "string"
    }
  },
  "success": true
}

Filter runs and group them by one or two dimensions into aggregates (count, failure rate, tokens, cost, duration, tool calls, signal fire rate), each with sample execution ids to drill into. Reads trace headers on indexed columns; model and tool-call metrics probe spans and cap the window at 7 days.

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

agentIdslist of stringsOptional

agentVersionIdslist of stringsOptional

Hosted runs carry no agentVersionId on the trace header yet, so this filter matches ingested runs only.

cursorstringOptional

flowIdslist of stringsOptional

fromstringOptional

ISO 8601; default 7 days before to.

groupBylist of enumsOptional

includeChildrenbooleanOptional

Count subagent and nested-flow runs too; unscoped reads fold them by default.

includeToolCallsbooleanOptional

Tool-call percentiles per group. Reads spans, so the window is capped at 7 days. Default false.

limitintegerOptional1-200

modelstringOptional

Runs with any model call to this model. Reads spans, so the window is capped at 7 days.

signalstringOptional

Runs where this signal fired: key or key:value.

signalRatestringOptional

Fire rate of this signal (key or key:value) per group; uniform and filtered samples are reported apart.

sourceenumOptional

Allowed values:

statusenumOptional

Allowed values:

stopReasonstringOptional

surfaceIdstringOptional

tostringOptional

ISO 8601; default now. Windows over 30 days are refused.

Response

Aggregates

dataobject

successboolean

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

500

Internal Server Error

503

Service Unavailable Error