Query runs
Returns a paginated list of runs for the given projects within min/max start_time. Supports filters, cursor pagination, and selects to select fields to return.
ai_search cannot be combined with sem_filter. With full AI search enabled, ai_search translates natural language into query filters and time bounds and cannot be combined with explicit filter expressions. Otherwise, ai_search retains legacy semantic-only behavior. Use sem_filter for semantic-only matching combined with structured filters. AI search requires organization consent.
When semantic matching is needed, Accept: text/event-stream is required; requests without it return 406. AI search is unavailable on deployments that route queries to the v1 backend and returns 501 there.
Self-hosted deployments require LangSmith v0.16 or later.
Headers
Body
ai_search translates natural language into structured filters, semantic criteria and time bounds.
Cannot be combined with sem_filter. With full AI search enabled, also cannot be combined with explicit filter expressions; otherwise retains legacy semantic-only behavior.
Must contain nonempty text of at most 2000 UTF-8 bytes. Not supported on public dataset queries.
1 - 2000"The customer was charged twice"
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.
"and(eq(run_type, \"llm\"), gt(latency, 5))"
include_subtree_usage enriches selected token and cost fields on root and intermediate runs with subtree totals, and selected first_token_time with the earliest observed subtree timestamp.
Descendants contribute regardless of this request's filters or time bounds. Runs without observed descendants retain their original values. Defaults to false.
max_feedback_modified_at is the exclusive upper bound (RFC3339) on feedback modified_at, applied to the feedback conditions in filter, trace_filter, or tree_filter (for example eq(feedback_key, "correctness")).
Requires at least one feedback condition. Runs must still fall within the start_time window.
"2024-12-31T23:59:59Z"
min_feedback_modified_at is the inclusive lower bound (RFC3339) on feedback modified_at, applied to the feedback conditions in filter, trace_filter, or tree_filter (for example eq(feedback_key, "correctness")).
Requires at least one feedback condition. Runs must still fall within the start_time window.
"2024-01-01T00:00:00Z"
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.
"018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327"
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.
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, LAST_QUEUED_AT, SHARE_URL, FEEDBACK_STATS, LS_USER_ID 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.
"eq(status, \"success\")"
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.
"has(tags, \"production\")"
Response
OK

