> ## Documentation Index > Fetch the complete documentation index at: https://docs.langchain.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /langsmith/langsmith-platform-openapi.json post /v2/threads/query openapi: 3.1.0 info: title: LangSmith description: >+ The LangSmith API is used to programmatically create and manage LangSmith resources. ## Host https://api.smith.langchain.com ## Authentication To authenticate with the LangSmith API, set the `X-Api-Key` header to a valid [LangSmith API key](https://docs.langchain.com/langsmith/create-account-api-key#create-an-api-key). version: 0.1.0 servers: - url: / security: [] tags: - name: run x-group: Tracing - name: runs x-group: Tracing - name: sessions x-group: Tracing - name: tracer-sessions x-group: Tracing - name: datasets x-group: Datasets - name: examples x-group: Datasets - name: evaluators x-group: Evaluation - name: experiment-view-overrides x-group: Evaluation - name: experiments x-group: Evaluation - name: annotation-queues x-group: Feedback & Annotation - name: annotation_queues x-group: Feedback & Annotation - name: feedback x-group: Feedback & Annotation - name: feedback-configs x-group: Feedback & Annotation - name: alert_rules x-group: Monitoring - name: bulk-exports x-group: Monitoring - name: charts x-group: Monitoring - name: commits x-group: Prompts & Playground - name: directories x-group: Prompts & Playground - name: hub_environments x-group: Prompts & Playground - name: playground-settings x-group: Prompts & Playground - name: prompt-webhooks x-group: Prompts & Playground - name: prompts x-group: Prompts & Playground - name: tag-transitions x-group: Prompts & Playground - name: comments x-group: Prompt Hub - name: likes x-group: Prompt Hub - name: optimization-jobs x-group: Prompt Hub - name: ownerships x-group: Prompt Hub - name: repos x-group: Prompt Hub - name: settings x-group: Prompt Hub - name: tags x-group: Prompt Hub - name: integrations x-group: Integrations & Tools - name: mcp x-group: Integrations & Tools - name: mcp_vendors x-group: Integrations & Tools - name: oauth x-group: Integrations & Tools - name: tools x-group: Integrations & Tools - name: gateway-policies x-group: LLM Gateway - name: sandboxes x-group: Sandboxes - name: issues x-group: Issues - name: issues-agent x-group: Issues - name: Organizations x-group: Administration - name: SCIM Tokens x-group: Administration - name: TTL Settings x-group: Administration - name: access_policies x-group: Administration - name: api-key x-group: Administration - name: audit-logs x-group: Administration - name: auth x-group: Administration - name: aws_marketplace x-group: Administration - name: data_planes x-group: Administration - name: me x-group: Administration - name: orgs x-group: Administration - name: service-accounts x-group: Administration - name: tenant x-group: Administration - name: ttl-settings x-group: Administration - name: usage-limits x-group: Administration - name: workspaces x-group: Administration - name: ace x-group: System - name: backfills x-group: System - name: features x-group: System - name: info x-group: System - name: model-price-map x-group: System - name: public x-group: System - name: threads x-group: System - name: agents x-hidden: true - name: beacon x-hidden: true - name: engine-trial - name: fleet - name: fleet auth x-hidden: true - name: fleet credentials x-hidden: true - name: fleet github-app x-hidden: true - name: fleet integrations x-hidden: true - name: fleet mcp x-hidden: true - name: fleet threads x-hidden: true - name: fleet trigger-templates x-hidden: true - name: fleet triggers x-hidden: true - name: fleet usage x-hidden: true - name: fleet_webhooks x-hidden: true - name: health - name: internal x-hidden: true - name: metrics x-hidden: true - name: nps x-hidden: true - name: sandboxes-internal x-hidden: true - name: skills x-hidden: true paths: /v2/threads/query: post: tags: - threads summary: Query Threads description: |- **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. parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/threads.QueryThreadsRequestBody' responses: '200': description: items and pagination content: application/json: schema: $ref: '#/components/schemas/threads.QueryThreadsResponseBody' '400': description: bad request (malformed JSON or invalid parameters) content: application/json: schema: $ref: '#/components/schemas/shared.ProblemDetails' '401': description: missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/shared.ProblemDetails' '403': description: forbidden (insufficient permission) content: application/json: schema: $ref: '#/components/schemas/shared.ProblemDetails' '404': description: session not found content: application/json: schema: $ref: '#/components/schemas/shared.ProblemDetails' '422': description: unprocessable entity (e.g. invalid project UUID) content: application/json: schema: $ref: '#/components/schemas/shared.ProblemDetails' '500': description: internal server error content: application/json: schema: $ref: '#/components/schemas/shared.ProblemDetails' '503': description: service unavailable content: application/json: schema: $ref: '#/components/schemas/shared.ProblemDetails' '504': description: gateway timeout or deadline exceeded content: application/json: schema: $ref: '#/components/schemas/shared.ProblemDetails' security: - API Key: [] Tenant ID: [] - Bearer Auth: [] Tenant ID: [] components: schemas: threads.QueryThreadsRequestBody: type: object properties: cursor: description: >- `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. type: string filter: description: >- `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. type: string max_start_time: description: >- `max_start_time` is the inclusive upper bound on thread activity (RFC3339 date-time). type: string format: date-time min_start_time: description: >- `min_start_time` is the inclusive lower bound on thread activity (RFC3339 date-time). type: string format: date-time page_size: description: >- `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. type: integer default: 20 maximum: 100 minimum: 1 example: 20 project_id: description: '`project_id` is the tracing project UUID.' type: string format: uuid example: 0190a1b2-c3d4-7ef0-a5b6-6ea3a82e9328 threads.QueryThreadsResponseBody: type: object properties: items: description: >- `items` is the page of thread summaries, sorted by the thread's most recent activity. type: array items: $ref: '#/components/schemas/threads.ThreadListItem' next_cursor: description: >- `next_cursor` is the opaque cursor to pass as `cursor` on the next request. Omitted on the final page. type: string example: eyJydW5zX2N1cnNvciI6Imx0KGN1cnNvciwiLi4uIikifQ== shared.ProblemDetails: description: RFC 7807 problem details returned on V2 API errors. type: object properties: detail: type: string instance: type: string remedy: description: Remedy is a LangSmith extension for user-recoverable errors. type: string status: type: integer title: type: string type: type: string threads.ThreadListItem: type: object properties: count: description: >- `count` is how many root traces (conversation turns) fall in this thread for the query time range. type: integer example: 3 feedback_stats: description: >- `feedback_stats` is the aggregated feedback across traces in the thread, keyed by feedback key; shape matches `feedback_stats` on a single run. allOf: - $ref: '#/components/schemas/query.RunFeedbackStats' first_inputs: description: >- `first_inputs` is a truncated preview of inputs from the earliest trace in the thread for the query window. type: string first_trace_id: description: >- `first_trace_id` is the root trace UUID for the chronologically first trace in the query time window. type: string format: uuid example: 018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327 last_error: description: >- `last_error` is a short error summary from the most recent failing trace in the thread. Absent when there is no error in the window. type: string last_outputs: description: >- `last_outputs` is a truncated preview of outputs from the latest trace in the thread for the query window. type: string last_trace_id: description: >- `last_trace_id` is the root trace UUID for the chronologically last trace in the query time window. type: string format: uuid example: 0190a1b2-c3d4-7ef0-a5b6-6ea3a82e9328 latency_p50: description: >- `latency_p50` is the approximate median end-to-end latency of traces in the thread, in seconds. type: number example: 0.15 latency_p99: description: >- `latency_p99` is the approximate 99th percentile end-to-end latency of traces in the thread, in seconds. type: number example: 0.42 max_start_time: description: >- `max_start_time` is the latest trace start time in the thread (RFC3339 date-time). type: string format: date-time example: '2025-01-15T12:05:00.000Z' min_start_time: description: >- `min_start_time` is the earliest trace start time in the thread (RFC3339 date-time). type: string format: date-time example: '2025-01-15T12:00:00.000Z' num_errored_turns: description: >- `num_errored_turns` is the count of root traces in the thread (within the query window) whose status was an error. type: integer example: 1 start_time: description: >- `start_time` is a reference start time for this row (RFC3339 date-time), such as for sorting. type: string format: date-time example: '2025-01-15T12:00:00.000Z' thread_id: description: >- `thread_id` identifies this conversation thread within the project from the request body `project_id`. type: string format: uuid example: 018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9327 total_cost: description: '`total_cost` is the sum of estimated USD cost across those traces.' type: number example: 0.045 total_cost_details: description: >- `total_cost_details` sums per-category estimated USD cost across traces in the thread. Keys mirror `total_token_details`. Example: `{"cache_read": 0.012, "reasoning": 0.008}`. type: object additionalProperties: type: number format: float64 total_token_details: description: >- `total_token_details` sums per-category token counts across traces in the thread. Keys are model-specific category names (for example `cache_read`, `cache_write`, `reasoning`, `audio`). Example: `{"cache_read": 400, "reasoning": 120}`. type: object additionalProperties: type: integer format: int64 total_tokens: description: '`total_tokens` is the sum of token usage across those traces.' type: integer example: 450 trace_id: description: >- `trace_id` is a representative root trace UUID when the summary includes one, for example for deep links. type: string format: uuid example: 018e4c7e-a9fb-7ef0-a5b6-6ea3a82e9328 query.RunFeedbackStats: type: object additionalProperties: $ref: '#/components/schemas/query.RunFeedbackStat' query.RunFeedbackStat: type: object properties: avg: description: >- `avg` is the arithmetic mean of numeric feedback scores for this key on the run, or `null` when no numeric score has been recorded (for example purely categorical feedback). type: number example: 0.87 comments: description: >- `comments` is a sample of human-readable comments attached to feedback points for this key, in no particular order. May be empty; is not exhaustive when many comments exist. type: array items: type: string example: - good answer - needs citation contains_thread_feedback: description: >- `contains_thread_feedback` is true when at least one feedback point for this key was submitted at the thread level (rather than at an individual run). Always false on responses that already describe a single run in isolation. type: boolean example: false errors: description: >- `errors` is the number of feedback points recorded as errors rather than successful scores (for example an automated evaluator that raised an exception). Defaults to 0 when no errors occurred. type: integer default: 0 example: 0 max: description: >- `max` is the largest numeric feedback score recorded for this key on the run, or `null` when no numeric score has been recorded. type: number example: 0.95 min: description: >- `min` is the smallest numeric feedback score recorded for this key on the run, or `null` when no numeric score has been recorded. type: number example: 0.8 'n': description: >- `n` is the number of feedback points recorded for this key on the run. For numeric feedback this is the sample size behind `avg`, `min`, `max`, and `stdev`; for categorical feedback it is the sum of the `values` counts. type: integer example: 42 sources: description: >- `sources` is a sample of feedback sources for this key. Each entry is either a plain string identifier (for example `"api"`, `"app"`, `"model"`) or a JSON object describing a synthetic source (for example `{"type": "__ls_composite_feedback"}` for a computed aggregate). Clients must tolerate both shapes. type: array items: {} stdev: description: >- `stdev` is the sample standard deviation of numeric feedback scores for this key on the run, or `null` when it cannot be computed (for example fewer than two numeric scores, or purely categorical feedback). type: number example: 0.05 values: description: >- `values` is the distribution of categorical feedback labels for this key, mapping each label to its occurrence count. Empty (`{}`) for purely numeric feedback. type: object additionalProperties: type: integer format: int64 securitySchemes: API Key: type: apiKey in: header name: X-API-Key Tenant ID: type: apiKey in: header name: X-Tenant-Id Bearer Auth: type: http description: >- Bearer tokens are used to authenticate from the UI. Must also specify x-tenant-id or x-organization-id (for org scoped apis). scheme: bearer ````