threads

Query Threads

Changed on

GET with body payload — no resources created. Returns the threads in a tracing project matching the query passed as the request payload. Results are filtered by the given time range and optional filters, with cursor-based pagination.

When ai_search is set, Accept: text/event-stream is required; requests without it return 406. AI search is unavailable on deployments that route queries to the v1 backend and returns 501 there.

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

post/api/v2/threads/query

Request

  • Base URL
    https://api.smith.langchain.com
  • URL
    https://api.smith.langchain.com/api/v2/threads/query
  • 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

Headers

Acceptstring

application/json, or text/event-stream (required when ai_search is set)

Request body

ai_searchstring

ai_search is a plain-language criterion evaluated against the messages from the agent trajectory scoped to the thread. AND-ed with the ordinary filters. Requires semantic filtering enabled for the deployment. Must contain nonempty text of at most 2000 UTF-8 bytes.

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 exclusive upper bound on thread activity (RFC3339 date-time). Defaults to now (UTC) when omitted.

min_start_timestring date-time

min_start_time is the inclusive lower bound on thread activity (RFC3339 date-time). Defaults to 1 day before now (UTC) when omitted.

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 non-null.

project_idstring uuid

project_id is the tracing project UUID.

thread_filterstring

thread_filter narrows results using a LangSmith filter expression evaluated against each complete thread summary. Self-hosted deployments require LangSmith v0.17 or later; unsupported deployments return 501. See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

trace_filterstring

trace_filter narrows results to threads containing at least one trace whose root run matches this LangSmith filter expression. Trace-level aggregate fields are evaluated using the complete trace summary. Self-hosted deployments require LangSmith v0.17 or later; unsupported deployments return 501. See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

tree_filterstring

tree_filter narrows results to threads containing at least one trace with a matching run anywhere in its run tree. Self-hosted deployments require LangSmith v0.17 or later; unsupported deployments return 501. See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

Example request

{
  "ai_search": "A conversation about a refund request",
  "page_size": 20,
  "project_id": "0190a1b2-c3d4-7ef0-a5b6-6ea3a82e9328",
  "thread_filter": "gte(turn_count, 3)",
  "trace_filter": "eq(status, \"error\")",
  "tree_filter": "has(tags, \"production\")"
}

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": [
    {
      "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=="
}

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

    • info

      removed the non-success response with the status

  • 1a8ee9358d81Revision changes
    • info

      endpoint added