---
title: "List Sessions"
method: GET
path: "/api/v1/public/sessions"
tags: ["Sessions"]
---

# List Sessions

`GET /api/v1/public/sessions`

## Request

- Base URL: `https://app.traceroot.ai`
- URL: `https://app.traceroot.ai/api/v1/public/sessions`
- Auth: HTTP bearer

List unique sessions for the caller's project with trace counts.

Args:
    auth (DualStampedAuth): Resolved credential context (API key or user
        session token); scopes the read to its project and stamps the
        rate-limit identity.
    limit (int): Items per page (1-200).
    search_query (str | None): Substring match on session id.
    start_after (datetime | None): Inclusive lower bound on trace time.
    end_before (datetime | None): Exclusive upper bound on trace time.

Returns:
    SessionListResponse: Session summaries, newest first.

Raises:
    HTTPException: 500 on a reader failure.

## Query parameters

- `limit` integer: Items per page
- `search_query` string, nullable: Search by session_id
- `start_after` string, date-time, nullable: Only sessions with traces at or after this time (inclusive, ISO 8601)
- `end_before` string, date-time, nullable: Only sessions with traces before this time (exclusive, ISO 8601)
- `project_id` string, nullable: Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.

## Response `200`

Successful Response

- SessionListResponse: Paginated list of sessions.
  - `data` SessionListItem[], required
    - `duration_ms` number, nullable, required
    - `first_trace_time` string, date-time, nullable, required
    - `input` string, nullable, required
    - `last_trace_time` string, date-time, nullable, required
    - `output` string, nullable, required
    - `session_id` string, required
    - `total_cost` number, nullable
    - `total_input_tokens` integer, nullable, required
    - `total_output_tokens` integer, nullable, required
    - `trace_count` integer, required
    - `user_ids` string[], required
  - `meta` PaginationMeta, required: Pagination metadata for list responses.
    - `limit` integer, required
    - `page` integer, required
    - `total` integer, required

## Other responses

- `401`: Authentication failed
- `422`: Validation Error
- `500`: Failed to list sessions
- `503`: Authentication service unavailable

---

[API](https://skmtc.dev/traceroot/apis/traceroot-public-api.md) - [All operations](https://skmtc.dev/traceroot/apis/traceroot-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/traceroot/apis/traceroot-public-api/revisions/ce6aef96c0d6?raw)