Sign in
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"
}

Changes

Changed in 2 of the 48 revisions of this API.29

  • a0acb3a6a10128See the full diff
    • ○

      the endpoint scheme security API Key AND Tenant ID was added to the API

      api-security-added

    • ○

      the endpoint scheme security Bearer Auth AND Tenant ID was added to the API

      api-security-added

    • ○

      the endpoint scheme security API Key was removed from the API

      api-security-removed

    • ○

      the endpoint scheme security Bearer Auth was removed from the API

      api-security-removed

    • ○

      the endpoint scheme security Tenant ID was removed from the API

      api-security-removed

    • ○

      added the non-success response with the status 403

      response-non-success-status-added

    • ○

      added the non-success response with the status 422

      response-non-success-status-added

    • ○

      added the non-success response with the status 500

      response-non-success-status-added

    • ○

      added the non-success response with the status 503

      response-non-success-status-added

    • ○

      added the non-success response with the status 504

      response-non-success-status-added

    • ○

      added the optional property detail to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property detail to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property detail to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property instance to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property instance to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property instance to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property remedy to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property remedy to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property remedy to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property status to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property status to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property status to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property title to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property title to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property title to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property type to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property type to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property type to the response with the 404 status

      response-optional-property-added

    This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 99490d1e837e1See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 15 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog