Skip to main content
GET
/
v1
/
traces
List traces with cursor-based pagination
curl --request GET \
  --url https://api.trulayer.ai/v1/traces \
  --header 'Authorization: Bearer <token>'
{
  "traces": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "error": "<string>",
      "tags": [
        "<string>"
      ],
      "started_at": "2023-11-07T05:31:56Z",
      "session_id": "<string>",
      "external_id": "<string>",
      "name": "<string>",
      "input": "<string>",
      "output": "<string>",
      "model": "<string>",
      "latency_ms": 123,
      "cost": 123,
      "total_token_count": 123,
      "prompt_tokens_total": 123,
      "completion_tokens_total": 123,
      "tag_map": {},
      "metadata": {},
      "span_count": 123,
      "control_loop_depth": 123,
      "spans": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "created_at": "2023-11-07T05:31:56Z",
          "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "trace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "type": "llm",
          "parent_span_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "input": "<string>",
          "output": "<string>",
          "model": "<string>",
          "latency_ms": 123,
          "cost": 123,
          "error": "<string>",
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "metadata": {},
          "start_time": "2023-11-07T05:31:56Z",
          "end_time": "2023-11-07T05:31:56Z",
          "otel_trace_id": "<string>",
          "otel_span_id": "<string>"
        }
      ],
      "ended_at": "2023-11-07T05:31:56Z"
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.trulayer.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

SDK API key (tl_...) or Clerk session JWT

Query Parameters

​
project_id
string<uuid>
​
model
string
​
error
boolean
​
failure_type
enum<string>

Filter traces with spans matching this failure type (e.g. timeout, rate_limit, invalid_response, context_length)

Available options:
timeout,
rate_limit,
invalid_response,
context_length
​
from
string<date-time>
​
to
string<date-time>
​
latency_min
integer

Minimum trace latency in milliseconds (inclusive). Must be a non-negative integer.

Required range: x >= 0
​
latency_max
integer

Maximum trace latency in milliseconds (inclusive). Must be a non-negative integer and greater than or equal to latency_min when both are supplied.

Required range: x >= 0
​
token_count_min
integer

Minimum total token count (prompt + completion, summed across spans) for the trace (inclusive). Must be a non-negative integer. Traces ingested before TRU-250 report total_token_count = 0 and are therefore excluded by any non-zero minimum.

Required range: x >= 0
​
token_count_max
integer

Maximum total token count for the trace (inclusive). Must be a non-negative integer and greater than or equal to token_count_min when both are supplied.

Required range: x >= 0
​
tag_key
string

Filter traces whose tags column contains the tag_key → tag_value pair (TRU-215). Must be supplied together with tag_value; providing only one side returns 400 error.tags_filter_incomplete.

​
tag_value
string

Filter value paired with tag_key. See tag_key for constraints.

​
cursor
string
​
limit
integer
default:50
Required range: 1 <= x <= 200

Response

Trace list

​
traces
object[]
required
​
has_more
boolean
required
​
next_cursor
string | null