Sign in

v48

latestOpenAPI 3.1.0raw.githubusercontent.com2026-05-275867561.6 MB
runs

Get a single run

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.

get/v2/runs/{run_id}

Path parameters

run_idstring uuid required

Run UUID

Query parameters

project_idstring uuid required

project_id is the UUID of the tracing project that owns the run.

selectsstring[]

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.

start_timestring date-time required

start_time is the run's start_time (RFC3339 date-time), used together with project_id to locate the run.

Headers

Acceptstring

application/json

Response

OK

app_pathstring

app_path identifies the application code location that produced this run, if recorded.

attachmentsQueryRunAttachmentURLs
completion_costnumber

completion_cost is estimated USD cost for the completion.

completion_tokensinteger

completion_tokens is the completion-side token count.

dotted_orderstring

dotted_order is the hierarchical ordering key for trace trees.

end_timestring date-time

end_time is when the run ended (RFC3339 date-time). JSON null if the run has not finished yet.

errorstring

error is the error message when status indicates failure.

error_previewstring

error_preview is a truncated plain-text error snippet.

extraobject

extra is additional runtime JSON attached to the run.

feedback_statsQueryRunFeedbackStats
first_token_timestring date-time

first_token_time is when the first output token was produced (RFC3339 date-time), when recorded for streamed runs.

idstring uuid

id is this run's UUID.

inputsobject

inputs is the run input payload (arbitrary JSON object).

inputs_previewstring

inputs_preview is a truncated plain-text preview of inputs.

is_in_datasetboolean

is_in_dataset is true when this run is linked to a dataset example.

is_rootboolean

is_root is true when this run has no parent (it is the trace root).

latency_secondsnumber

latency_seconds is wall-clock duration from start to end in seconds.

manifestobject

manifest is the serialized configuration of the traced component (for example the model parameters, prompt template, or pipeline definition), when recorded.

metadataobject

metadata is arbitrary user-defined JSON metadata.

namestring

name is a human-readable label for the run (for example the model name, function name, or step name chosen when the run was traced).

outputsobject

outputs is the run output payload (arbitrary JSON object).

outputs_previewstring

outputs_preview is a truncated plain-text preview of outputs.

parent_run_idsstring[]

parent_run_ids lists ancestor run UUIDs from the trace root down to the direct parent.

price_model_idstring uuid

price_model_id identifies the pricing model UUID used for cost estimates, when recorded.

project_idstring uuid

project_id is the tracing project UUID this run was logged to.

prompt_costnumber

prompt_cost is estimated USD cost for the prompt.

prompt_tokensinteger

prompt_tokens is the prompt-side token count.

reference_dataset_idstring uuid

reference_dataset_id is the dataset UUID for the reference example, if any.

reference_example_idstring uuid

reference_example_id is the dataset example UUID this run was compared against, if any.

run_type'TOOL' | 'CHAIN' | 'LLM' | 'RETRIEVER' | 'EMBEDDING' | 'PROMPT' | 'PARSER'
share_urlstring

share_url is the fully-qualified URL of this run's public view, rooted at the deployment's LangSmith app origin (for example https://smith.langchain.com/public/4f7a1b2c-8d9e-4a0b-9c1d-2e3f4a5b6c7d/r). It is returned only when SHARE_URL is included in selects, and only when the run has been explicitly shared; the URL remains stable until the run is unshared. Anyone with this URL can view the run anonymously, so treat it as a secret and do not log it.

start_timestring date-time

start_time is when the run started (RFC3339 date-time).

status'SUCCESS' | 'ERROR' | 'PENDING'
tagsstring[]

tags lists user-defined tags on this run.

thread_evaluation_timestring date-time

thread_evaluation_time is thread-level evaluation timing (RFC3339 date-time), when recorded.

thread_idstring uuid

thread_id is the conversation thread UUID this run belongs to, if any.

total_costnumber

total_cost is total estimated USD cost (prompt plus completion).

total_tokensinteger

total_tokens is prompt plus completion tokens.

trace_idstring uuid

trace_id is the root trace UUID; for a root run it matches id.

Example response

{
  "app_path": "/app/chains/chat.py:invoke",
  "completion_cost": 0.0003,
  "completion_tokens": 150,
  "dotted_order": "20240115T103000000000Z018e4c7ea9fb7ef0a5b66ea3a82e9327.",
  "end_time": "2024-01-15T10:30:01.500Z",
  "error": "context deadline exceeded",
  "events": [
    {
      "name": "new_token",
      "time": "2024-01-15T10:30:00.312Z"
    }
  ],
  "first_token_time": "2024-01-15T10:30:00.312Z",
  "id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
  "is_in_dataset": true,
  "is_root": true,
  "latency_seconds": 1.523,
  "name": "ChatOpenAI",
  "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_tokens": 200,
  "reference_dataset_id": "c3d4e5f6-a7b8-4c5d-0e1f-2a3b4c5d6e7f",
  "reference_example_id": "b2c3d4e5-f6a7-4b5c-9d0e-1f2a3b4c5d6e",
  "share_url": "https://smith.langchain.com/public/4f7a1b2c-8d9e-4a0b-9c1d-2e3f4a5b6c7d/r",
  "start_time": "2024-01-15T10:30:00.000Z",
  "tags": [
    "production",
    "gpt-4"
  ],
  "thread_id": "d4e5f6a7-b8c9-4d5e-1f2a-3b4c5d6e7f8a",
  "total_cost": 0.000525,
  "total_tokens": 350,
  "trace_id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327"
}