threads

Query Thread Traces

Changed on

Retrieve all traces belonging to a specific thread within a project.

Self-hosted deployments require LangSmith v0.16 or later.

get/api/v2/threads/{thread_id}/traces

Request

  • Base URL
    https://api.smith.langchain.com
  • URL
    https://api.smith.langchain.com/api/v2/threads/{thread_id}/traces
  • Auth
    • API key in header X-API-Key and API key in header X-Tenant-Id
    • or HTTP bearer and API key in header X-Tenant-Id

Path parameters

thread_idstring required

Thread ID

Query parameters

cursorstring

cursor is the opaque string from a previous response's next_cursor. Omit on the first request; pass the returned cursor to fetch the next page.

filterstring

filter narrows which traces are returned for this thread, using a LangSmith filter expression evaluated against each root trace run. For example: eq(status, "success") or has(tags, "production"). See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

page_sizeinteger

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

project_idstring uuid required

project_id is the tracing project UUID (required).

selectsstring[]

selects lists which properties to include on each returned trace (repeatable query parameter). Accepts any value of the ThreadTraceSelectField enum. Properties not listed are omitted from each trace object; trace_id is always returned.

trace_filterstring

trace_filter narrows traces by applying a LangSmith filter expression to each trace's root run.

tree_filterstring

tree_filter narrows traces to those containing at least one run that matches the LangSmith filter expression.

Response

items and pagination

next_cursorstring

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

Example response

{
  "items": [
    {
      "end_time": "2025-01-15T12:00:01.500Z",
      "error": "context deadline exceeded",
      "first_token_time": "2024-01-15T10:30:00.312Z",
      "start_time": "2025-01-15T12:00:00.000Z",
      "thread_id": "d4e5f6a7-b8c9-4d5e-1f2a-3b4c5d6e7f8a",
      "trace_id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
      "turn_number": 1
    }
  ],
  "next_cursor": "eyJydW5zX2N1cnNvciI6Imx0KGN1cnNvciwiLi4uIikifQ=="
}

Changes

  • 52b146f318d7Revision changes
    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

  • 1a8ee9358d81Revision changes
    • info

      endpoint added