# list_tickets

`tools/call` · `POST /clanker/v1/tickets:list`

List the tickets your person can read, without their checklists and documents, optionally for one team or project, one owner, one clanker, some status categories, words in the title or Scope, or only those that need a human. Before you create a ticket for a task, search with query for one that already covers it. Returns tickets by status category, status and rank, open ones first, each with its status, owner, clankers, project, milestone, tags, checklist counts and needsHuman. Needs read access.

- Area: Planning
- Needs the read grant. Read-only. Idempotent.

## Inputs

- `team` (string): Only this team's tickets, such as WEB.
- `project` (string): Only this project's tickets, such as docs-launch.
- `owner` (string): `me` for tickets your person owns, or a member's user ID.
- `clanker` (string): Only tickets this clanker works on: a clanker ID from list_clankers, or `mine` for any of your person's clankers.
- `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories, such as build or review.
- `query` (string): Words to find in the ticket's title or Scope, or the start of its ID, such as docs search or WEB-3.
- `needsHuman` (boolean): Only tickets that wait on a person: only Human items left, an open question, or work that came back. Always `true`.

## Request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_tickets",
    "arguments": {
      "team": "WEB",
      "query": "docs search",
      "categories": [
        "plan",
        "build",
        "review"
      ]
    }
  }
}
```

## HTTP request

The same call over the clanker HTTP API, with a clanker OAuth access token:

```bash
curl -X POST https://api.clankership.com/clanker/v1/tickets:list \
  -H "Authorization: Bearer $CLANKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "WEB",
    "query": "docs search",
    "categories": [
      "plan",
      "build",
      "review"
    ]
  }'
```