list_tickets
Retrieve a project's Strategic Tickets page by page and filter by status, owner, priority, due date, or origin to see what the team is deciding on or working on.
Instructions
List a project's Strategic Tickets, a page at a time — what its team is deciding on and working on, whether a person opened a ticket, the customer's own automation did, or a Strategic Briefing did. Every tool that takes a ticketId also takes a ticket's number as a person writes it, '#14'; here, a person's #14 is number=14. Returns { items, pagination: { page, limit, total, totalPages, hasMore }, byStatus }. pagination.total counts every match across pages — quote it, never the length of items; hasMore says a next page exists — ask for page+1. byStatus counts the matches per column whatever status you passed, narrowed by every other filter, so limit=1 with no other filter is the board's census. Each row is a summary: every field except the Markdown description, which is not on the row until you pass include=['description'] — get_ticket always has it. The parameters carry the one-call recipes: sort='priority' with status=['triage','todo'] for what to start, maxMinutes for quick wins, dueBefore for overdue and this week, activeSince for what changed. Due dates are calendar days with no time zone: pass the customer's own today. By default the list is the board flattened: the columns in the order triage, todo, in_progress, done, dismissed, and inside each column the order the team keeps — in triage that starts as the order an edition delivered its recommendations, most important first, newest edition on top, until somebody moves them. One edition's tickets: origin='briefing' with its runId as briefingRunId (from get_briefing or get_briefing_history). To read neighbours for move_ticket, use sort='board' (the default) and the destination column alone. A ticket's description and every comment are Markdown.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Return only the tickets whose title or description contains this text, compared without regard to case. It is matched literally — punctuation is text, not a pattern — and threads are not searched. A match in a description is weaker evidence than one in the title: a briefing's description quotes its grounding, so read the ticket before calling two tickets the same work | |
| page | No | Which page, from 1 (the default). pagination.hasMore says whether a next one exists | |
| sort | No | The order of the list: 'board', 'priority', 'due', 'activity'. 'board' (the default) is the board as the team sees it and the only order to read move_ticket neighbours from. What to start: status=['triage','todo'], sort='priority'. 'priority' puts the highest impact first; among the same impact, the least effort first, and among the same effort the fewest minutes of the edition's estimate; then the earliest due date, then board order. A missing value sorts last at each step. 'due' puts the earliest due date first, undated last. 'activity' puts the most recently touched first. Any order but 'board' mixes the columns; each ticket carries its status. | |
| limit | No | How many tickets per page, 1 to 100; 50 when omitted. Pass limit=1 when you only need pagination.total and byStatus | |
| effort | No | Return only the tickets sized as one of these — one, or several: ['low','medium']. Tickets nobody sized are left out. This is the ticket's size word, not its minutes: a briefing's estimatedMinutes is the edition's own time estimate, neither is derived from the other, and a 'low' ticket can be an afternoon — when a person asks for something quick, use maxMinutes on list_tickets. | |
| number | No | Return the one ticket carrying this number on the board — what a person means by #14 | |
| origin | No | Who opened the ticket, never which dimension it is about (that is `dimension`): user — a person in the app; api — an API key, which is what everything you write here carries; briefing — a Strategic Briefing; ai_sources — reserved for a future AI Sources writer, which opens none today, so that value matches none. | |
| status | No | Return only the tickets in these columns — one, or several: ['todo','in_progress']. Omit it for every column. byStatus ignores this filter, so its counts still cover every column, narrowed by every other filter you passed. What the columns mean: triage — nobody has decided yet, and you cannot know whether anyone looked at it; todo — decided and not started; in_progress — being worked on; done — the team moved it there, never proof the work was good or that a measurement moved because of it: put a ticket beside a number as two facts with their dates, joined by no verb; dismissed — the team decided not to do it. The set is fixed and a project cannot add to it. | |
| dueFrom | No | Return only the tickets due on or after this calendar day, YYYY-MM-DD. Tickets with no due date are left out. A due date has no time zone, so pass the customer's own day | |
| include | No | Ask for each ticket's Markdown description in the list. Left out by default: one ticket's description runs to thousands of characters, so a page fetched with them is large enough to be worth asking for on purpose. get_ticket always returns it | |
| labelId | No | Return only the tickets carrying one label — its ID from list_ticket_labels | |
| assignee | No | Return only the tickets one person owns — their user ID from list_ticket_assignees, or 'none' for the tickets nobody owns. A ticket whose owner has left the organization reads as unassigned everywhere, but is still found here by their ID | |
| dimension | No | Return only the tickets a Strategic Briefing opened for one part of its analysis, or 'none' for the tickets no part claims — everything a person or an API key opened, and a briefing's ticket whose edition named none. 'agent-readiness' is the key for Agent Adoption; the key predates the name and does not change | |
| dueBefore | No | Return only the tickets due strictly before this calendar day, YYYY-MM-DD. Overdue: status=['triage','todo','in_progress'], dueBefore=<today>, sort='due'. Due this week: the same columns, dueFrom=<today>, dueBefore=<the day after the week ends>. Tickets with no due date are left out. A due date has no time zone, so pass the customer's own day | |
| impactMin | No | Return only the tickets whose impact is at least this, 1 to 4 (1 Minor · 2 Moderate · 3 Significant · 4 Critical; 4 matters most). Tickets nobody sized are left out | |
| projectId | Yes | Project ID (from list_projects) | |
| maxMinutes | No | Return only the tickets a Strategic Briefing opened whose edition estimated at most this many minutes of work. Quick wins: status=['triage','todo'], impactMin=3, maxMinutes=120, sort='priority'. A ticket without an edition's estimate — everything a person or an API key opened, and a briefing's ticket the edition did not size — is left out; for those, effort=['low'] instead | |
| activeSince | No | Return only the tickets something happened to at or after this moment — an edit, a move, or a new thread entry (lastActivityAt). Changed since yesterday: activeSince=<the start of the customer's yesterday>, sort='activity'. ISO 8601 with its offset; a time without one is read as UTC, and YYYY-MM-DD is the start of that day in UTC. On a changed ticket, a statusChangedAt later than this means it changed column, and a lastActivityAt later than its updatedAt means a thread entry was written or edited after the ticket's own last change. A deleted ticket is gone and does not appear | |
| briefingRunId | No | Return only the tickets one Strategic Briefing edition opened — its runId, from get_briefing or get_briefing_history. They come back whole, finished and dismissed ones included, so the list matches the count the briefing states |