---
title: "List trace threads"
method: POST
path: "/v2/sessions/query"
tags: ["Threads"]
---

# List trace threads

`POST /v2/sessions/query`

List trace threads from your workspace.

## Request body

- ListThreadsRequest
  - `filters` ThreadFilters, required
    - `interval` 'SESSION_INTERVAL_UNSPECIFIED' | 'SESSION_INTERVAL_ALL_TIME' | 'SESSION_INTERVAL_LAST_30_MINUTES' | 'SESSION_INTERVAL_LAST_1_HOUR' | 'SESSION_INTERVAL_LAST_6_HOURS' | 'SESSION_INTERVAL_LAST_24_HOURS' | 'SESSION_INTERVAL_LAST_3_DAYS' | 'SESSION_INTERVAL_LAST_7_DAYS' | 'SESSION_INTERVAL_LAST_14_DAYS' | 'SESSION_INTERVAL_LAST_1_MONTH' | 'SESSION_INTERVAL_LAST_3_MONTHS', required
    - `project_id` string
    - `tags` string[]
    - `start_date` string — Start of a custom activity window in unix milliseconds.
    - `end_date` string — End of a custom activity window in unix milliseconds.
    - `client` string
    - `repo` string
    - `kind` 'THREAD_KIND_UNSPECIFIED' | 'THREAD_KIND_CONVERSATION' | 'THREAD_KIND_CODING_AGENT'
  - `limit` integer
  - `page` integer

## Response `200`

OK

- ListThreadsResponse
  - `object` string, required
  - `data` Thread[], required
    - `_id` string, required — Internal thread record ID.
    - `external_id` string, required — Client-provided thread identifier used to group related traces.
    - `duration` number, double, required — Total thread duration in milliseconds.
    - `contact_ids` string[], required — Contact IDs associated with the thread.
    - `billing` ThreadBilling, required
      - `input_cost` number, double, required
      - `output_cost` number, double, required
      - `total_cost` number, double, required
    - `usage` ThreadUsage, required
      - `prompt_tokens` integer, required
      - `completion_tokens` integer, required
      - `total_tokens` integer, required
    - `traces_count` integer, required — Number of traces associated with the thread.
    - `tags` string[], required — Tags used to categorize the thread.
    - `project_id` string
    - `started_at` string, date-time
    - `updated_at` string, date-time
    - `title` string — Display title. Does not replace external_id and is not used to group traces.
    - `client` string — Originating coding assistant or client, such as claude-code, cursor, or codex.
    - `repo` string — Canonical git repository for a coding-agent thread, such as github.com/org/repo.
    - `kind` 'THREAD_KIND_UNSPECIFIED' | 'THREAD_KIND_CONVERSATION' | 'THREAD_KIND_CODING_AGENT'
  - `has_more` boolean, required

## Changes

> 350 revisions in range; 136 not diffed.

- **2026-09-07** `bcd6172f8655` — 1 info
  - endpoint added
- **2026-09-07** `dcc0afb98a48` — 1 breaking
  - api path removed without deprecation
- **2026-09-06** `e1a2869bc12f` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/sessions/query/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/3c7d859558ee?raw)