Error

A valid request URL is required to generate request examples

{
  "items": [
    {
      "root_run": {
        "app_path": "/app/chains/chat.py:invoke",
        "attachments": {
          "{\"output.png\"": "\"https://storage.example.com/bucket/key?X-Amz-Signature=abc\"}"
        },
        "completion_cost": 0.0003,
        "completion_cost_details": {
          "raw": {}
        },
        "completion_token_details": {
          "raw": {}
        },
        "completion_tokens": 150,
        "dotted_order": "20240115T103000000000Z018e4c7ea9fb7ef0a5b66ea3a82e9327.",
        "end_time": "2024-01-15T10:30:01.500Z",
        "error": "context deadline exceeded",
        "error_preview": "<string>",
        "events": [
          {
            "kwargs": {},
            "name": "new_token",
            "time": "2024-01-15T10:30:00.312Z"
          }
        ],
        "extra": {},
        "feedback_stats": {},
        "first_token_time": "2024-01-15T10:30:00.312Z",
        "id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
        "inputs": {},
        "inputs_preview": "<string>",
        "is_in_dataset": true,
        "is_root": true,
        "latency_seconds": 1.523,
        "manifest": {},
        "metadata": {},
        "name": "ChatOpenAI",
        "outputs": {},
        "outputs_preview": "<string>",
        "parent_run_ids": [
          "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
          "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
        ],
        "price_model_id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b",
        "project_id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
        "prompt_cost": 0.0002,
        "prompt_cost_details": {
          "raw": {}
        },
        "prompt_token_details": {
          "raw": {}
        },
        "prompt_tokens": 200,
        "reference_dataset_id": "c3d4e5f6-a7b8-4c5d-0e1f-2a3b4c5d6e7f",
        "reference_example_id": "b2c3d4e5-f6a7-4b5c-9d0e-1f2a3b4c5d6e",
        "run_type": "LLM",
        "share_url": "https://smith.langchain.com/public/4f7a1b2c-8d9e-4a0b-9c1d-2e3f4a5b6c7d/r",
        "start_time": "2024-01-15T10:30:00.000Z",
        "status": "SUCCESS",
        "tags": [
          "production",
          "gpt-4"
        ],
        "thread_evaluation_time": "2023-11-07T05:31:56Z",
        "thread_id": "d4e5f6a7-b8c9-4d5e-1f2a-3b4c5d6e7f8a",
        "total_cost": 0.000525,
        "total_tokens": 350,
        "trace_id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327"
      },
      "trace_aggregates": {
        "first_token_time": "2023-11-07T05:31:56Z",
        "total_cost": 123,
        "total_tokens": 123
      }
    }
  ],
  "next_cursor": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

Query traces

Returns a paginated list of traces (root runs) for a single tracing project. Each item carries the trace’s root run plus optional trace-wide aggregates (total_tokens, total_cost, first_token_time) under trace_aggregates, so clients never have to merge by trace_id.

Traces are scanned within a start_time window: min_start_time defaults to 24 hours before the request, max_start_time defaults to the request time. Set either explicitly to widen or narrow the window.

Supports filters (trace_filter, tree_filter), cursor pagination (cursor), and field projection (selects).

POST

traces

query

Error

A valid request URL is required to generate request examples

{
  "items": [
    {
      "root_run": {
        "app_path": "/app/chains/chat.py:invoke",
        "attachments": {
          "{\"output.png\"": "\"https://storage.example.com/bucket/key?X-Amz-Signature=abc\"}"
        },
        "completion_cost": 0.0003,
        "completion_cost_details": {
          "raw": {}
        },
        "completion_token_details": {
          "raw": {}
        },
        "completion_tokens": 150,
        "dotted_order": "20240115T103000000000Z018e4c7ea9fb7ef0a5b66ea3a82e9327.",
        "end_time": "2024-01-15T10:30:01.500Z",
        "error": "context deadline exceeded",
        "error_preview": "<string>",
        "events": [
          {
            "kwargs": {},
            "name": "new_token",
            "time": "2024-01-15T10:30:00.312Z"
          }
        ],
        "extra": {},
        "feedback_stats": {},
        "first_token_time": "2024-01-15T10:30:00.312Z",
        "id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
        "inputs": {},
        "inputs_preview": "<string>",
        "is_in_dataset": true,
        "is_root": true,
        "latency_seconds": 1.523,
        "manifest": {},
        "metadata": {},
        "name": "ChatOpenAI",
        "outputs": {},
        "outputs_preview": "<string>",
        "parent_run_ids": [
          "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
          "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
        ],
        "price_model_id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b",
        "project_id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
        "prompt_cost": 0.0002,
        "prompt_cost_details": {
          "raw": {}
        },
        "prompt_token_details": {
          "raw": {}
        },
        "prompt_tokens": 200,
        "reference_dataset_id": "c3d4e5f6-a7b8-4c5d-0e1f-2a3b4c5d6e7f",
        "reference_example_id": "b2c3d4e5-f6a7-4b5c-9d0e-1f2a3b4c5d6e",
        "run_type": "LLM",
        "share_url": "https://smith.langchain.com/public/4f7a1b2c-8d9e-4a0b-9c1d-2e3f4a5b6c7d/r",
        "start_time": "2024-01-15T10:30:00.000Z",
        "status": "SUCCESS",
        "tags": [
          "production",
          "gpt-4"
        ],
        "thread_evaluation_time": "2023-11-07T05:31:56Z",
        "thread_id": "d4e5f6a7-b8c9-4d5e-1f2a-3b4c5d6e7f8a",
        "total_cost": 0.000525,
        "total_tokens": 350,
        "trace_id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327"
      },
      "trace_aggregates": {
        "first_token_time": "2023-11-07T05:31:56Z",
        "total_cost": 123,
        "total_tokens": 123
      }
    }
  ],
  "next_cursor": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "instance": "<string>",
  "remedy": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

Authorizations

X-API-Key

string

header

required

X-Tenant-Id

string

header

required

Headers

Content-Type

string

application/json (required for JSON body)

Body

application/json

cursor

string

cursor is the opaque string returned in a previous response's next_cursor.

max_start_time

string<date-time>

max_start_time is the exclusive upper bound for the root-run start time scan (RFC3339). Defaults to the request time when omitted.

Example:

"2024-12-31T23:59:59Z"

min_start_time

string<date-time>

min_start_time is the inclusive lower bound for the root-run start time scan (RFC3339). Defaults to 24 hours before the request when omitted.

Example:

"2024-01-01T00:00:00Z"

page_size

integer

default:20

page_size is the maximum number of traces to return per page. Defaults to 20; must be between 1 and 100 when set.

Required range: 1 <= x <= 100

Example:

20

project_id

string<uuid>

project_id is the UUID of the tracing project that owns the traces. Required.

Example:

"018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327"

selects

enum<string>[]

selects lists which properties to include on each returned trace. Properties listed here are routed to the appropriate sub-object on each item: total_tokens, total_cost, and first_token_time appear under trace_aggregates; everything else appears under root_run. If omitted, only id is returned on root_run.

Available options:

ID,

NAME,

RUN_TYPE,

STATUS,

START_TIME,

END_TIME,

LATENCY_SECONDS,

FIRST_TOKEN_TIME,

ERROR,

ERROR_PREVIEW,

EXTRA,

METADATA,

EVENTS,

INPUTS,

INPUTS_PREVIEW,

OUTPUTS,

OUTPUTS_PREVIEW,

MANIFEST,

PARENT_RUN_IDS,

PROJECT_ID,

TRACE_ID,

THREAD_ID,

DOTTED_ORDER,

IS_ROOT,

REFERENCE_EXAMPLE_ID,

REFERENCE_DATASET_ID,

TOTAL_TOKENS,

PROMPT_TOKENS,

COMPLETION_TOKENS,

TOTAL_COST,

PROMPT_COST,

COMPLETION_COST,

PROMPT_TOKEN_DETAILS,

COMPLETION_TOKEN_DETAILS,

PROMPT_COST_DETAILS,

COMPLETION_COST_DETAILS,

PRICE_MODEL_ID,

TAGS,

APP_PATH,

ATTACHMENTS,

THREAD_EVALUATION_TIME,

IS_IN_DATASET,

SHARE_URL,

FEEDBACK_STATS

Example:

[
  "ID",
  "NAME",
  "START_TIME",
  "STATUS",
  "TOTAL_TOKENS",
  "TOTAL_COST",
  "FIRST_TOKEN_TIME"
]

trace_filter

string

trace_filter narrows results to traces whose root run matches this LangSmith filter expression. This filter targets root runs only — is_root = true is implied. See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

Example:

"eq(status, \"error\")"

trace_ids

string<uuid>[]

trace_ids is an optional fast-path restriction to a known set of trace UUIDs. Equivalent in result to including each UUID in a trace_filter, but more efficient at scale.

tree_filter

string

tree_filter narrows results to traces containing at least one run anywhere in the run tree (root or descendant) that matches this LangSmith filter expression.

Example:

"has(tags, \"production\")"

Response

items

object[]

items is the page of traces.

Show child attributes

next_cursor

string

next_cursor is the opaque cursor for the next page. Null on the final page.

Query Thread Traces

List runs in a trace