---
title: "POST /tracer/trace-session/list_sessions/"
method: POST
path: "/tracer/trace-session/list_sessions/"
tags: ["tracer"]
---

# POST /tracer/trace-session/list_sessions/

`POST /tracer/trace-session/list_sessions/`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/tracer/trace-session/list_sessions/`
- Auth: one of:
  - API key in header `X-Api-Key`
  - API key in header `X-Secret-Key`

List traces filtered by project ID and project version ID with optimized queries.

## Request body

- TraceSessionListQuery
  - `project_id` string, uuid
  - `user_id` string
  - `bookmarked` boolean, nullable
  - `filters` string: JSON-encoded canonical filter list. On trace, span, session, graph, and eval-task bounded reads, created_at/start_time datetime filters support equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, between, not_equals, not_between, is_null, and is_not_null. Missing bounds retain the finite default window: 30 days ago for the lower bound and request-time now for the upper bound. Between and not_between use half-open [start, end) ranges; not_equals excludes one DateTime64(6) microsecond. Because the physical created_at/start_time field is non-null, is_null returns an exact empty result without a ClickHouse read and is_not_null preserves the base window. Valid contradictions also return an exact empty result.
  - `sort_params` string: JSON-encoded list of sort params.
  - `page_number` integer: Zero-based numbered page. Pages whose required ordered work exceeds the finite read contract return HTTP 422 with code page_depth_exceeded; request an earlier page or narrow the time range.
  - `page_size` integer
  - `cursor` string: Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter.
  - `cursor_mode` boolean
  - `interval` string
  - `allow_sampled` boolean: Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total, or true to opt in explicitly to lower-bound totals.

## Response `200`

OK

- TraceSessionListResponse
  - `status` boolean, required
  - `result` TraceSessionListResult, required
    - `metadata` TraceSessionListMetadata, required
      - `total_rows` integer, required
      - `total_rows_exact` integer, nullable
      - `total_rows_is_lower_bound` boolean
      - `has_more` boolean
      - `next_cursor` string, nullable
      - `next_cursor_fingerprint` string, nullable
      - `query_complete` boolean
      - `query_status` 'complete' | 'degraded'
      - `query_error_code` string, nullable
      - `query_elapsed_ms` number
      - `query_count` integer
      - `query_rows_returned` integer
      - `query_result_payload_bytes` integer
      - `query_applied_filter_version` 'canonical-json-sha256-v1'
      - `query_applied_filter_sha256` string
      - `query_applied_filter_count` integer
      - `query_exact` boolean
      - `ordering_exact` boolean
      - `query_provenance` 'spans_per_session_candidate'
    - `table` TraceSessionTableRow[], required
      - `session_id` string, nullable
      - `session_name` string, nullable
      - `project_id` string, uuid, nullable
      - `start_time` string, date-time, nullable
      - `end_time` string, date-time, nullable
      - `created_at` string, date-time, nullable
      - `duration` number, nullable
      - `total_cost` number, nullable
      - `total_tokens` integer, nullable
      - `total_traces_count` integer, nullable
      - `first_message` object, nullable: Any valid JSON value.
      - `last_message` object, nullable: Any valid JSON value.
      - `user_id` string, nullable
      - `user_id_type` string, nullable
      - `user_id_hash` string, nullable
    - `config` TraceObserveColumnConfig[], required
      - `id` string, required
      - `name` string, required
      - `is_visible` boolean, required
      - `group_by` string, nullable
      - `output_type` string, nullable
      - `reverse_output` boolean, nullable
      - `annotation_label_type` string, nullable
      - `choices` string[], nullable
      - `settings` object, nullable: Any valid JSON value.
      - `choices_map` object, nullable: Any valid JSON value.
      - `eval_template_id` string, nullable
      - `target_type` 'span' | 'trace', nullable
      - `annotators` object, nullable: Any valid JSON value.
      - `source_field` string, nullable
      - `parent_eval_id` string, nullable
      - `property_id` string, nullable
      - `property_kind` string, nullable
      - `property_source` string, nullable

## Other responses

- `400`: Bad Request
- `422`: Unprocessable Entity
- `500`: Internal Server Error
- `503`: Service Unavailable
- `default`: Default error response

---

[API](https://skmtc.dev/futureagi/apis/future-agi-management-api.md) · [All operations](https://skmtc.dev/futureagi/apis/future-agi-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/futureagi/apis/future-agi-management-api/revisions/c8684118e142?raw)