openapi: 3.1.0
info:
title: LangSmith access_policies runs API
description: 'The LangSmith API is used to programmatically create and manage LangSmith resources.
## Host
https://api.smith.langchain.com
## Authentication
To authenticate with the LangSmith API, set the `X-Api-Key` header
to a valid [LangSmith API key](https://docs.langchain.com/langsmith/create-account-api-key#create-an-api-key).
'
version: 0.1.0
servers:
- url: /
tags:
- name: runs
paths:
/runs:
post:
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
description: Queues a single run for ingestion. The request body must be a JSON-encoded run object that follows the Run schema.
tags:
- runs
summary: Create a Run
parameters: []
responses:
'202':
description: Run created
content:
application/json:
schema:
type: object
additionalProperties:
allOf:
- type: string
- type: object
properties:
message:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/runs.Run'
/runs/batch:
post:
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
description: 'Ingests a batch of runs in a single JSON payload. The payload must have `post` and/or `patch` arrays containing run objects.
Prefer this endpoint over single‑run ingestion when submitting hundreds of runs, but `/runs/multipart` offers better handling for very large fields and attachments.'
tags:
- runs
summary: Ingest Runs (Batch JSON)
parameters: []
responses:
'202':
description: Runs batch ingested
content:
application/json:
schema:
type: object
additionalProperties:
allOf:
- type: string
- type: object
properties:
message:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
patch:
type: array
items:
$ref: '#/components/schemas/runs.Run'
post:
type: array
items:
$ref: '#/components/schemas/runs.Run'
/runs/multipart:
post:
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
description: 'Ingests multiple runs, feedback objects, and binary attachments in a single `multipart/form-data` request.
**Part‑name pattern**: `<event>.<run_id>[.<field>]` where `event` ∈ {`post`, `patch`, `feedback`, `attachment`}.
* `post|patch.<run_id>` – JSON run payload.
* `post|patch.<run_id>.<field>` – out‑of‑band run data (`inputs`, `outputs`, `events`, `error`, `extra`, `serialized`).
* `feedback.<run_id>` – JSON feedback payload (must include `trace_id`).
* `attachment.<run_id>.<filename>` – arbitrary binary attachment stored in S3.
**Headers**: every part must set `Content-Type` **and** either a `Content-Length` header or `length` parameter. Per‑part `Content-Encoding` is **not** allowed; the top‑level request may be `Content-Encoding: gzip` or `Content-Encoding: zstd`.
**Best performance** for high‑volume ingestion.'
tags:
- runs
summary: Ingest Runs (Multipart)
parameters: []
responses:
'202':
description: Accepted
content:
application/json:
schema:
type: object
additionalProperties:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
post.{run_id}:
type: string
format: binary
description: Run to create (JSON)
patch.{run_id}:
type: string
format: binary
description: Run to update (JSON)
post.{run_id}.inputs:
type: string
format: binary
description: Large inputs object (JSON) stored out‑of‑band
patch.{run_id}.outputs:
type: string
format: binary
description: Large outputs object (JSON) stored out‑of‑band
feedback.{run_id}:
type: string
format: binary
description: Feedback object (JSON) – must include trace_id
attachment.{run_id}.{filename}:
type: string
format: binary
description: Binary attachment linked to run {run_id}
/runs/{run_id}:
patch:
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
description: Updates a run identified by its ID. The body should contain only the fields to be changed; unknown fields are ignored.
tags:
- runs
summary: Update a Run
parameters:
- description: Run ID
name: run_id
in: path
required: true
schema:
type: string
format: uuid
responses:
'202':
description: Run updated
content:
application/json:
schema:
type: object
additionalProperties:
allOf:
- type: string
- type: object
properties:
message:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/runs.ErrorResponse'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/runs.Run'
/v2/runs/query:
post:
security:
- API Key: []
Tenant ID: []
- Bearer Auth: []
Tenant ID: []
description: '**Alpha:** The request and response contract may change;
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.'
tags:
- runs
summary: Query runs
parameters:
- description: application/json
name: Accept
in: header
schema:
type: string
- description: application/json (required for JSON body)
name: Content-Type
in: header
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/query.QueryRunsResponseBody'
'400':
description: bad request (malformed JSON or invalid parameters)
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'401':
description: missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'403':
description: forbidden (insufficient permission)
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'404':
description: session not found
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'422':
description: unprocessable entity (e.g. invalid UUID)
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'500':
description: internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'503':
description: service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'504':
description: gateway timeout or deadline exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/query.QueryRunsRequestBody'
/v2/runs/{run_id}:
get:
security:
- API Key: []
Tenant ID: []
- Bearer Auth: []
Tenant ID: []
description: '**Alpha:** The request and response contract may change;
Returns one run by ID for the given session and start_time. Use the `selects` query parameter (repeatable) to select fields to return.'
tags:
- runs
summary: Get a single run
parameters:
- description: application/json
name: Accept
in: header
schema:
type: string
- description: Run UUID
name: run_id
in: path
required: true
schema:
type: string
format: uuid
- description: '`project_id` is the UUID of the tracing project that owns the run.'
name: project_id
in: query
required: true
schema:
type: string
format: uuid
title: Project Id
- description: '`selects` lists which properties to include on the returned run (repeatable query parameter). Accepts any value of the `RunSelectField` enum. If omitted, only `id` is returned.'
name: selects
in: query
style: form
explode: true
schema:
items:
enum:
- 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
type: string
type: array
title: Selects
- description: '`start_time` is the run''s `start_time` (RFC3339 date-time), used together with `project_id` to locate the run.'
name: start_time
in: query
required: true
schema:
type: string
format: date-time
title: Start Time
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/query.RunResponse'
'400':
description: bad request (missing or invalid query parameters)
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'401':
description: missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'403':
description: forbidden (insufficient permission)
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'404':
description: run or session not found
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'422':
description: unprocessable entity (e.g. invalid UUID)
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'500':
description: internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'503':
description: service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'504':
description: gateway timeout or deadline exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
/v2/traces/{trace_id}/runs:
get:
security:
- API Key: []
Tenant ID: []
- Bearer Auth: []
Tenant ID: []
description: '**Alpha:** The request and response contract may change;
Returns runs for a trace ID within min/max start time. Optional `filter`; repeatable `selects` to select fields to return.'
tags:
- runs
summary: List runs in a trace
parameters:
- description: application/json
name: Accept
in: header
schema:
type: string
- description: Trace UUID
name: trace_id
in: path
required: true
schema:
type: string
format: uuid
- description: '`filter` narrows which runs within this trace are returned, using a LangSmith filter expression evaluated against each run. For example: `eq(run_type, "llm")` for LLM runs only, or `eq(status, "error")` for failed runs.
See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.'
name: filter
in: query
schema:
type: string
title: Filter
- description: '`max_start_time` is the inclusive upper bound for run `start_time` (RFC3339 date-time).'
name: max_start_time
in: query
required: true
schema:
type: string
format: date-time
title: Max Start Time
- description: '`min_start_time` is the inclusive lower bound for run `start_time` (RFC3339 date-time).'
name: min_start_time
in: query
required: true
schema:
type: string
format: date-time
title: Min Start Time
- description: '`project_id` is the UUID of the tracing project that owns the trace.'
name: project_id
in: query
required: true
schema:
type: string
format: uuid
title: Project Id
- description: '`selects` lists which properties to include on each returned run (repeatable query parameter). Accepts any value of the `RunSelectField` enum. If omitted, only `id` is returned.'
name: selects
in: query
style: form
explode: true
schema:
items:
enum:
- 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
type: string
type: array
title: Selects
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/query.QueryTraceResponseBody'
'400':
description: bad request (missing or invalid query parameters)
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'401':
description: missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'403':
description: forbidden (insufficient permission)
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'404':
description: session not found
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'422':
description: unprocessable entity (e.g. invalid UUID)
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'500':
description: internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'503':
description: service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
'504':
description: gateway timeout or deadline exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/shared.ProblemDetails'
components:
schemas:
query.QueryRunsResponseBody:
type: object
properties:
has_more:
description: '`has_more` is true when another page of runs exists after this one.'
type: boolean
example: true
items:
description: '`items` is the page of runs, sorted by `start_time` in the direction given by the request `sort_order`.'
type: array
items:
$ref: '#/components/schemas/query.RunResponse'
next_cursor:
description: '`next_cursor` is the opaque cursor to pass as `cursor` on the next request when `has_more` is true. Omitted on the final page.'
type: string
example: eyJsYXN0X2lkIjoiMDE4ZTRjN2UtYTlmYi03ZWYwLWE1YjYtNmVhM2E4MmU5MzI3In0=
query.RunEvent:
type: object
properties:
kwargs:
description: '`kwargs` is the event payload — an opaque JSON object whose shape depends on `name` and on the emitting SDK. For example LangChain emits `{"token": {...}}` for `new_token` events, tool-call start/end details for tool events, and arbitrary user-defined payloads for custom events. Clients should treat `kwargs` as untyped JSON: do not assume specific keys exist for a given `name`, and tolerate additional unknown keys appearing over time.'
type: object
name:
description: '`name` is the event kind. Common values emitted by the LangChain/LangSmith tracer SDKs include `"start"`, `"end"`, and `"new_token"`, but applications may emit arbitrary strings for their own instrumentation.'
type: string
example: new_token
time:
description: '`time` is when the event occurred (RFC3339 date-time with millisecond precision).'
type: string
format: date-time
example: '2024-01-15T10:30:00.312Z'
query.QueryTraceResponseBody:
type: object
properties:
items:
description: '`items` lists runs in the trace for the requested time window, in `start_time` order.'
type: array
items:
$ref: '#/components/schemas/query.RunResponse'
query.RunAttachmentURLs:
type: object
additionalProperties:
type: string
query.RunSelectField:
type: string
enum:
- 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
x-enum-varnames:
- RunSelectID
- RunSelectName
- RunSelectRunType
- RunSelectStatus
- RunSelectStartTime
- RunSelectEndTime
- RunSelectLatencySeconds
- RunSelectFirstTokenTime
- RunSelectError
- RunSelectErrorPreview
- RunSelectExtra
- RunSelectMetadata
- RunSelectEvents
- RunSelectInputs
- RunSelectInputsPreview
- RunSelectOutputs
- RunSelectOutputsPreview
- RunSelectManifest
- RunSelectParentRunIDs
- RunSelectProjectID
- RunSelectTraceID
- RunSelectThreadID
- RunSelectDottedOrder
- RunSelectIsRoot
- RunSelectReferenceExampleID
- RunSelectReferenceDatasetID
- RunSelectTotalTokens
- RunSelectPromptTokens
- RunSelectCompletionTokens
- RunSelectTotalCost
- RunSelectPromptCost
- RunSelectCompletionCost
- RunSelectPromptTokenDetails
- RunSelectCompletionTokenDetails
- RunSelectPromptCostDetails
- RunSelectCompletionCostDetails
- RunSelectPriceModelID
- RunSelectTags
- RunSelectAppPath
- RunSelectAttachments
- RunSelectThreadEvaluationTime
- RunSelectIsInDataset
- RunSelectShareURL
- RunSelectFeedbackStats
query.RunType:
type: string
enum:
- TOOL
- CHAIN
- LLM
- RETRIEVER
- EMBEDDING
- PROMPT
- PARSER
x-enum-varnames:
- RunTypeTool
- RunTypeChain
- RunTypeLLM
- RunTypeRetriever
- RunTypeEmbedding
- RunTypePrompt
- RunTypeParser
query.RunFeedbackStat:
type: object
properties:
avg:
description: '`avg` is the arithmetic mean of numeric feedback scores for this key on the run, or `null` when no numeric score has been recorded (for example purely categorical feedback).'
type: number
example: 0.87
comments:
description: '`comments` is a sample of human-readable comments attached to feedback points for this key, in no particular order. May be empty; is not exhaustive when many comments exist.'
type: array
items:
type: string
example:
- good answer
- needs citation
contains_thread_feedback:
description: '`contains_thread_feedback` is true when at least one feedback point for this key was submitted at the thread level (rather than at an individual run). Always false on responses that already describe a single run in isolation.'
type: boolean
example: false
errors:
description: '`errors` is the number of feedback points recorded as errors rather than successful scores (for example an automated evaluator that raised an exception). Defaults to 0 when no errors occurred.'
type: integer
default: 0
example: 0
max:
description: '`max` is the largest numeric feedback score recorded for this key on the run, or `null` when no numeric score has been recorded.'
type: number
example: 0.95
min:
description: '`min` is the smallest numeric feedback score recorded for this key on the run, or `null` when no numeric score has been recorded.'
type: number
example: 0.8
n:
description: '`n` is the number of feedback points recorded for this key on the run. For numeric feedback this is the sample size behind `avg`, `min`, `max`, and `stdev`; for categorical feedback it is the sum of the `values` counts.'
type: integer
example: 42
sources:
description: '`sources` is a sample of feedback sources for this key. Each entry is either a plain string identifier (for example `"api"`, `"app"`, `"model"`) or a JSON object describing a synthetic source (for example `{"type": "__ls_composite_feedback"}` for a computed aggregate). Clients must tolerate both shapes.'
type: array
items: {}
stdev:
description: '`stdev` is the sample standard deviation of numeric feedback scores for this key on the run, or `null` when it cannot be computed (for example fewer than two numeric scores, or purely categorical feedback).'
type: number
example: 0.05
values:
description: '`values` is the distribution of categorical feedback labels for this key, mapping each label to its occurrence count. Empty (`{}`) for purely numeric feedback.'
type: object
additionalProperties:
type: integer
format: int64
runs.ErrorResponse:
type: object
properties:
details:
description: Optional error details as JSON string
type: string
example: '{"field":"dataset_id","reason":"required"}'
error:
description: Error message
type: string
example: 'Invalid request: missing required fields'
query.SortOrder:
type: string
enum:
- ASC
- DESC
x-enum-varnames:
- SortOrderAsc
- SortOrderDesc
query.RunFeedbackStats:
type: object
additionalProperties:
$ref: '#/components/schemas/query.RunFeedbackStat'
query.RunCompletionTokenDetails:
type: object
properties:
raw:
description: '`raw` maps each category name to its completion-token count.'
type: object
additionalProperties:
type: integer
format: int64
query.QueryRunsRequestBody:
type: object
properties:
ai_query:
description: '`ai_query` is a natural-language query to filter runs using AI.'
type: string
example: runs that used tool calls
cursor:
description: '`cursor` is the opaque string from a previous response''s `next_cursor`.'
type: string
example: eyJsYXN0X2lkIjoiMDE4ZTRjN2UtYTlmYi03ZWYwLWE1YjYtNmVhM2E4MmU5MzI3In0=
filter:
description: '`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.'
type: string
example: and(eq(run_type, "llm"), gt(latency, 5))
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/langsmith/refs/heads/main/openapi/langsmith-runs-api-openapi.yml