List approval requests
list_approval_requestsList approval requests visible to this user, newest first. Use to answer 'what is waiting on me' and 'what did I submit'. Filter by status; by scope (created_by_me / awaiting_my_approval); by workflow name with workflow_query; by submission date with created_after / created_before (YYYY-MM-DD, inclusive); by free text with search. To filter on a FIELD's value — 'invoices from Acme', 'where Country is Germany', 'anything with a laptop on it' — use field_filters, a list of {label, value}. The label is the field's name on the form, and columns inside line-item tables are matched too, so this reaches values search cannot. Set include_field_values to read the requests' actual field values back. count is the total number of matches; the response carries one page. When truncated is true, call again with offset raised by limit rather than describing the page as the whole set.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10). Capped at 20 normally, or 50 with `include_field_values` so there is enough of a sample to reason over. | |
| scope | No | Whose requests to list. 'all' (default): every request the user can see. 'created_by_me': only ones they submitted. 'awaiting_my_approval': only ones waiting on THIS user's decision right now — they're the pending approver on the current step (also includes requests sent back to them for changes). Use 'awaiting_my_approval' for 'what do I need to approve'; it already implies the right statuses, so don't also pass `status`. | all |
| offset | No | Skip this many before returning. With `limit` this is how you page through a set larger than one call can carry: `count` says how many match in total, so when `truncated` is true, call again with `offset` raised by `limit`. Never describe a page as the whole set. | |
| search | No | Free-text search over the request's searchable content (AR number, pipeline/stage names, indexed field text). Use when the user describes a request rather than naming it. Prefer `workflow_query` when they name the workflow itself. | |
| status | No | Optional status filter. | |
| approver_id | No | TeamUser id of the person whose approval is PENDING right now (from `search_team_users`). Use for 'what's pending on Julia', 'what is waiting on the CFO'. This is the ONLY way to answer that — `scope=awaiting_my_approval` is the CURRENT user's queue and must never be presented as someone else's. Results are still limited to requests you're allowed to see. | |
| requestor_id | No | TeamUser id of the person who SUBMITTED the requests (from `search_team_users`). Use for 'what has Sarah submitted'. For the current user prefer `scope=created_by_me`. Results are still limited to requests you're allowed to see. | |
| created_after | No | Only requests submitted ON or after this date (YYYY-MM-DD). | |
| field_filters | No | Narrow to requests whose FIELD VALUES match, by the field's name on the form. This is how you answer 'invoices from Acme', 'requests where Country is Germany', or 'which requests have a laptop on them' — the last one works because line-item table columns are matched too, not just fields on the form itself. Combine freely with the other filters; several entries all have to match the same request. Prefer this over `search` when the user names a field and a value, because `search` is free text over the whole request and will also match a mention in a description. Use `get_workflow_details` if unsure what a workflow calls a field. | |
| created_before | No | Only requests submitted ON or before this date (YYYY-MM-DD, inclusive of the whole day). | |
| workflow_query | No | Optional substring to match workflow name (case-insensitive). | |
| include_field_values | No | Return each request's actual field values (vendor, amount, dates, description, whatever that workflow defines) so YOU can analyse them and answer the question directly. Set this whenever the user asks something about request CONTENT that the other filters can't express — 'which of these mention a rush', 'what do the rejected ones have in common', 'which vendor comes up most', 'are any of these duplicates', 'why is this taking so long'. The filters narrow WHICH requests; this gives you WHAT IS IN THEM. Combine with the filters to keep the set relevant and small. Requests whose values can't be read are counted in `field_values_unavailable`, not omitted silently — never present an analysis as complete when that number is above zero, or when `truncated` is true. |