--- title: "List the queue" method: GET path: "/products/help-desk/tickets" tags: ["help-desk"] --- # List the queue `GET /products/help-desk/tickets` ## Request - Base URL: `https://api.sparkvault.com/v1` - URL: `https://api.sparkvault.com/v1/products/help-desk/tickets` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) One page of a queue view: `all` (the whole desk, or one team with `team_id`), `team` (one team's), `mine` (the signed-in operator's) or `unassigned`, in the statuses asked for (at most four; open for all and team, every live status for mine and unassigned), newest activity first (`last_activity`) or the longest waiting first (`oldest_waiting`). `requester_id` lists one requester's tickets, in the order they were opened (newest first, or oldest first with `oldest_waiting`), narrowed by the view and the filters. `q` finds one ticket by its number, or lists the tickets of the requester an email address names, as `requester_id` does. Each row carries its requester and who is on it now. Any member, from their own session. ## Query parameters - `view` 'all' | 'mine' | 'unassigned' | 'team' - `status` string[] - `team_id` string - `assignee_id` string - `priority` string[] - `tag` string - `q` string - `requester_id` string - `sort` 'last_activity' | 'oldest_waiting' - `cursor` string - `limit` integer ## Response `200` A page of the queue. - object - `data` HelpDeskQueuePage, required - `items` HelpDeskQueueRow[], required - `ticket_id` string, required - `number` integer, required: The ticket's number at the desk (#1042). - `status` 'open' | 'waiting_on_customer' | 'on_hold' | 'closed', required - `close_reason` 'resolved' | 'duplicate' | 'spam' | 'null', nullable, required - `hold_until` integer, nullable, required: When a hold ends (epoch seconds). - `priority` 'urgent' | 'high' | 'normal' | 'low', required - `team_id` string, nullable, required - `assignee_id` string, nullable, required - `requester_id` string, required - `subject` string, required - `preview` string, required: The start of the ticket's first message, as plain text. - `tags` string[], required - `created_at` integer, required - `last_activity_at` integer, nullable, required - `last_customer_message_at` integer, nullable, required - `first_operator_reply_at` integer, nullable, required - `last_operator_reply_at` integer, nullable, required - `merged_into` string, nullable, required - `merged_into_number` integer, nullable, required - `muted` boolean, required: Whether its requester turned its update emails off. - `awaiting_first_response` boolean, required - `version` integer, required: The version a change is made against. - `requester` HelpDeskRequester, nullable, required: The ticket's requester, their address and name opened for the desk; null once the desk holds no row for them. - `requester_id` string, required - `display_name` string, nullable, required - `email` string, required - `assurance` 'identity' | 'email_pin', required: How they last proved their address. - `presence` HelpDeskPresenceEntry[]: Who is on the ticket now (the queue only). - `user_id` string, required - `state` 'viewing' | 'replying', required - `next_cursor` string, nullable, required: Opaque continuation token. Null when the listing is exhausted. - `partial` boolean: Present when the page was cut short by the read budget: follow next_cursor for the rest. - `meta` ResponseMeta: Envelope metadata present on every successful response. - `api_version` string - `request_id` string - `response_ms` integer - `timestamp` integer: Unix seconds. - `pools` object: Storage and bandwidth capacity snapshot for the account. - `billing` object - `past_due` boolean - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise. - `limit` integer - `used` integer - `remaining` integer - `resets_at` integer: Unix seconds. ## Other responses - `400`: VALIDATION_ERROR — a view, status, team, priority, tag, requester or query the queue does not read. INVALID_CURSOR — the cursor is another view's. - `401`: AUTHENTICATION_ERROR — missing or invalid credentials. - `403`: FORBIDDEN — the credential is an API key or an impersonated session: the help desk is worked from a member's own session. HELP_DESK_SUBSCRIPTION_REQUIRED — a change that needs the help desk, on an organization that does not hold it. - `409`: HELP_DESK_NOT_ACTIVE — the desk is not active. ## Changes - **2026-10-28** `a9a10e328ba5`: 16 info - the response property `error/details` became required for the status `400` - the response property `error/details` became required for the status `401` - the response property `error/details` became required for the status `403` - the response property `error/details` became required for the status `409` - …12 more - **2026-10-28** `56d7c265a77a`: 4 breaking - the response property `error/details` became nullable for the status `400` - the response property `error/details` became nullable for the status `401` - the response property `error/details` became nullable for the status `403` - the response property `error/details` became nullable for the status `409` - **2026-10-23** `ad4c62db5e08`: 1 info - endpoint added [Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/products/help-desk/tickets/get.md) --- [API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)