v48

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

threads

Query Threads

Alpha: The request and response contract may change; Query threads within a project (session), with cursor-based pagination. Returns threads matching the given time range and optional filter.

post/v2/threads/query

Request body

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 threads are returned, using a LangSmith filter expression evaluated against each thread's root run. For example: has(tags, "production") or eq(status, "error"). See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

max_start_timestring date-time

max_start_time is the inclusive upper bound on thread activity (RFC3339 date-time).

min_start_timestring date-time

min_start_time is the inclusive lower bound on thread activity (RFC3339 date-time).

page_sizeinteger

page_size is the maximum number of threads to return in this response. Defaults to 20 when omitted; must be between 1 and 100 inclusive when set. The response may contain fewer threads than page_size even when next_cursor is present.

project_idstring uuid

project_id is the tracing project UUID.

Example request

{
  "page_size": 20,
  "project_id": "0190a1b2-c3d4-7ef0-a5b6-6ea3a82e9328"
}

Response

items and pagination

next_cursorstring

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

Example response

{
  "items": [
    {
      "count": 3,
      "first_trace_id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
      "last_trace_id": "0190a1b2-c3d4-7ef0-a5b6-6ea3a82e9328",
      "latency_p50": 0.15,
      "latency_p99": 0.42,
      "max_start_time": "2025-01-15T12:05:00.000Z",
      "min_start_time": "2025-01-15T12:00:00.000Z",
      "num_errored_turns": 1,
      "start_time": "2025-01-15T12:00:00.000Z",
      "thread_id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327",
      "total_cost": 0.045,
      "total_tokens": 450,
      "trace_id": "018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9328"
    }
  ],
  "next_cursor": "eyJydW5zX2N1cnNvciI6Imx0KGN1cnNvciwiLi4uIikifQ=="
}