Query runs - Docs by LangChain

Error

A valid request URL is required to generate request examples

{
  "items": [
    {
      "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"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJhIjoicnVucy5xdWVyeSIsImsiOiJwYXNzIiwiYiI6InNkYiIsInQiOiJsdChjdXJzb3IsICcyMDI1LTEyLTEyIDE5OjAzOjI4LjQ4MTI1NTAxOWIxM2YyJykifQ"
}

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

POST

runs

query

Error

A valid request URL is required to generate request examples

{
  "items": [
    {
      "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"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJhIjoicnVucy5xdWVyeSIsImsiOiJwYXNzIiwiYiI6InNkYiIsInQiOiJsdChjdXJzb3IsICcyMDI1LTEyLTEyIDE5OjAzOjI4LjQ4MTI1NTAxOWIxM2YyJykifQ"
}

{
  "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

string

application/json

Content-Type

string

application/json (required for JSON body)

Body

application/json

cursor

string

cursor is the opaque string from a previous response's next_cursor. Treat it as opaque and pass it back unmodified.

Example:

"eyJ2IjoxLCJhIjoicnVucy5xdWVyeSIsImsiOiJwYXNzIiwiYiI6InNkYiIsInQiOiJsdChjdXJzb3IsICcyMDI1LTEyLTEyIDE5OjAzOjI4LjQ4MTI1NTAxOWIxM2YyJykifQ"

filter

string

filter narrows results to runs matching this LangSmith filter expression, evaluated against each individual run. For example: and(eq(run_type, "llm"), gt(latency, 5)) or eq(status, "error"). See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

Example:

"and(eq(run_type, \"llm\"), gt(latency, 5))"

has_error

boolean

has_error filters to runs that errored (true) or completed without error (false).

Example:

false

ids

string<uuid>[]

ids optionally limits the request to these run UUIDs.

Example:

[
  "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
  "f47ac10b-58cc-4372-a567-0e02b2c3d479"
]

is_root

boolean

is_root returns only root runs (true) or only non-root runs (false).

Example:

true

max_start_time

string<date-time>

max_start_time is the upper bound for run start_time (RFC3339). Defaults to now.

Example:

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

min_start_time

string<date-time>

min_start_time is the lower bound for run start_time (RFC3339). Defaults to 1 day ago.

Example:

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

page_size

integer

default:100

page_size is the maximum number of runs to return in this response. Defaults to 100 when omitted; must be between 1 and 1000 inclusive when set.

Required range: 1 <= x <= 1000

Example:

100

project_ids

string<uuid>[]

project_ids lists tracing project UUIDs to query. Required unless reference_dataset_id is set. Mutually exclusive with reference_dataset_id — set exactly one of them.

Example:

[
  "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
  "0190a1b2-c3d4-7ef0-a5b6-6ea3a82e9328"
]

reference_dataset_id

string<uuid>

reference_dataset_id resolves session IDs server-side from the dataset. Required unless project_ids is set. Mutually exclusive with project_ids — set exactly one of them. When provided and min_start_time is omitted, the server derives it from the earliest session creation date.

Example:

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

reference_examples

string<uuid>[]

reference_examples optionally limits to runs linked to these dataset example UUIDs.

Example:

[
  "b2c3d4e5-f6a7-4b5c-9d0e-1f2a3b4c5d6e",
  "c3d4e5f6-a7b8-4c5d-0e1f-2a3b4c5d6e7f"
]

run_type

enum<string>

run_type, when set, restricts results to runs whose run_type equals this value.

Available options:

TOOL,

CHAIN,

LLM,

RETRIEVER,

EMBEDDING,

PROMPT,

PARSER

Example:

"LLM"

selects

enum<string>[]

selects lists which properties to include on each returned run. If omitted, only id is returned. Properties not listed are omitted from each run object.

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",
  "PROJECT_ID",
  "START_TIME",
  "RUN_TYPE",
  "STATUS"
]

trace_filter

string

trace_filter narrows results to runs whose root trace matches this LangSmith filter expression. Use this to filter by properties of the trace's root run — for example eq(status, "success") to include only traces that completed without error. See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

Example:

"eq(status, \"success\")"

trace_id

string<uuid>

trace_id optionally limits results to runs belonging to this trace UUID.

Example:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

tree_filter

string

tree_filter narrows results to runs that belong to a trace containing at least one run matching this LangSmith filter expression anywhere in the run tree (not just the root). Use this to find runs inside traces that involved a specific tool, tag, or model — for example has(tags, "production") or eq(name, "my_tool"). See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

Example:

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

Response

items

object[]

items is the page of runs, sorted by start_time descending.

Show child attributes

next_cursor

string

next_cursor is the opaque cursor to pass as cursor on the next request. Null on the final page.

Example:

"eyJ2IjoxLCJhIjoicnVucy5xdWVyeSIsImsiOiJwYXNzIiwiYiI6InNkYiIsInQiOiJsdChjdXJzb3IsICcyMDI1LTEyLTEyIDE5OjAzOjI4LjQ4MTI1NTAxOWIxM2YyJykifQ"

Query public shared trace runs

Get a single run