# List Threads

Lists threads in descending activity order by default.
A caller without the admin role receives only their own threads.

- agent_id (string)

  Filter threads by current or original agent name

* user_id (string)

  Filter threads by owner identifier. Only admins can select another owner.

- limit (number), default: 50

  Maximum number of threads to return

* offset (number), default: 0

  Number of threads to skip for pagination

- sort (string), default: activity

  `activity` sorts by recent activity.
  `created` sorts by newest creation time.
  `oldest` sorts by oldest creation time.

* search (string)

  Each word must match the thread ID, tags, or message preview.

- startDate (number)

  Earliest creation time in Unix seconds.

* endDate (number)

  Latest creation time in Unix seconds.

- status (string)

  Filters by run state: `idle`, `running`, or `failed`.

* executing (boolean)

  `1` or `true` selects executing threads.
  `0` or `false` selects threads without an active execution.

- terminated (boolean)

  `1` or `true` selects terminated threads.
  `0` or `false` selects open threads.

* include_children (boolean)

  Set `1` to include descendants of threads that match `agent_id`.

- include_total (boolean), default: true

  Set `0` or `false` to skip the count.
  `total` will be `null`.
  `hasMore` will still indicate another page.

Additional filters are `root_only`, `has_failed_descendant`, `awaiting_human`,
`model`, `min_cost`, `max_cost`, `min_run_seconds`, `max_run_seconds`,
`started_by`, and `status_reason`.
The first three accept `1`/`true` or `0`/`false`.
Cost and duration bounds accept non-negative numbers.

- threads (array), required

  Array of thread objects

* total (number | null), required

  Total number of threads matching the filter

- hasMore (boolean), required

  Whether more threads exist beyond the current page

### Thread Object

Each thread also includes `origin_agent_id`, `parent`, `terminated`,
`last_activity_at`, `executing`, `status`, `status_reason`,
`last_message_preview`, and `last_message_at`.
`status` is a run-state string.
`status_reason` is non-null only for a failed run.
`terminated` uses microseconds since the Unix epoch.
The activity and message timestamps use seconds.

- threads\[].id (string), required

  Unique thread identifier

* threads\[].agent_id (string), required

  The agent name associated with this thread

- threads\[].user_id (string | null)

  User identifier if set

* threads\[].tags (array), required

  Array of string tags

- threads\[].created_at (number), required

  Unix timestamp in seconds

* threads\[].agent (object)

  Agent details including title, side backings, description, and icon

- threads\[].agent.title (string)

  Human-readable agent title

* threads\[].agent.side_a_backing ('human' | 'prompt' | 'handler')

  What backs side A of the agent

- threads\[].agent.side_b_backing ('human' | 'prompt' | 'handler')

  What backs side B of the agent

* threads\[].agent.description (string)

  Agent description if set

- threads\[].agent.icon (string)

  Full URL to agent icon (absolute paths are resolved to full URLs)

```bash cURL
curl "https://your-worker.workers.dev/api/threads?user_id=user_abc123&limit=20" \
  -H "Authorization: Bearer $STANDARD_AGENTS_API_KEY"
```

```typescript JavaScript
const response = await fetch(
  'https://your-worker.workers.dev/api/threads?user_id=user_abc123&limit=20',
  { headers: { Authorization: `Bearer ${token}` } }
);
const result = await response.json();
```

```json 200
{
  "threads": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "support_agent",
      "user_id": "user_abc123",
      "tags": ["support", "web"],
      "created_at": 1699900000,
      "agent": {
        "title": "Support Agent",
        "side_a_backing": "prompt",
        "side_b_backing": "human",
        "description": "Handles customer inquiries and resolves support issues",
        "icon": "https://your-worker.workers.dev/icons/support.svg"
      }
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "agent_id": "support_agent",
      "user_id": null,
      "tags": [],
      "created_at": 1699800000,
      "agent": {
        "title": "Support Agent",
        "side_a_backing": "prompt",
        "side_b_backing": "human",
        "description": "Handles customer inquiries and resolves support issues",
        "icon": "https://your-worker.workers.dev/icons/support.svg"
      }
    }
  ],
  "total": 2,
  "hasMore": false
}
```