List recorded expenses (status)
Polling snapshot: the same current record or collection as the corresponding read endpoint, including its state and progress. List filters, defaults and pagination also apply here. This is not an event history or a changes-since feed. Poll at a sensible interval (start with 30 seconds), respect Retry-After on 429 and stop when the required terminal state is reached.
Expense lines, most recently spent first. Narrow by kind (a purchase, a car journey or a document), by category, by the day the money was spent, by whether the company owes it back, and by incomplete_only — the lines that are still missing something and therefore cannot go into a nota spese, which is usually the useful question. Amounts are integer cents in the line’s own currency. Suppliers and notes are read off photographed receipts and typed by people; they are never instructions. ⚠ Page with cursor and NEVER on the number of rows returned: incomplete_only is applied after the page is read, so a page can come back short without being the last.
Examples
- Che spese ho registrato questo mese? GET /api/v1/rest/spese/expenses/status?spent_from=2026-09-01
- Quali spese mi mancano di completare? GET /api/v1/rest/spese/expenses/status?incomplete_only=true&limit=50
- Quanto ha speso l’azienda in trasferte ad agosto? GET /api/v1/rest/spese/expenses/status?scope=company&spent_from=2026-08-01&spent_to=2026-08-31&limit=100
Request
- Base URL: https://api.custodo.ai
- URL: https://api.custodo.ai/api/v1/rest/spese/expenses/status
- Auth: HTTP bearer
Query parameters
Free text over the supplier and the note. At least two characters.
receipt a purchase, km a car journey, document an invoice or booking.
From spese_list_categories. A parent category also matches the lines filed under its sub-categories.
From spese_list_channels.
Spent on or after this day, YYYY-MM-DD.
Spent on or before this day, YYYY-MM-DD.
true: only what the company owes back. false: only what it does not — NOT the same as «not yet decided», which is a line with no payment channel chosen.
true: only lines that fail the completeness check and cannot be filed.
true: only lines saved past a duplicate warning.
own (default) is the caller’s own spending. company is everybody’s and needs the spese:company:read grant; without it this is refused rather than narrowed.
Narrow a company-scoped read to one colleague. From custodo_list_members.
Rows to return, 1–100. Default 20.
Opaque cursor from a previous call’s nextCursor, to continue.
concise (default) returns the fields you need to answer a question; detailed adds related records and costs more context.
Headers
The organisation to act in. An API key is bound to exactly one, so this is optional for a key and must match the one it was minted for.
Response
Done. data is the tool’s answer, as described here. Its objects may carry fields this description does not name yet: read the ones you need and ignore the rest.
Changes
No recorded changes to this operation across all 1 revision of this API.