Expenses

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
get/api/v1/rest/spese/expenses/status

Request

  • Base URL: https://api.custodo.ai
  • URL: https://api.custodo.ai/api/v1/rest/spese/expenses/status
  • Auth: HTTP bearer

Query parameters

querystring

Free text over the supplier and the note. At least two characters.

kind'receipt' | 'km' | 'document'

receipt a purchase, km a car journey, document an invoice or booking.

category_idstring uuid

From spese_list_categories. A parent category also matches the lines filed under its sub-categories.

payment_channel_idstring uuid

From spese_list_channels.

spent_fromstring

Spent on or after this day, YYYY-MM-DD.

spent_tostring

Spent on or before this day, YYYY-MM-DD.

reimbursableboolean

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.

incomplete_onlyboolean

true: only lines that fail the completeness check and cannot be filed.

duplicates_onlyboolean

true: only lines saved past a duplicate warning.

scope'own' | 'company'

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.

owner_user_idstring uuid

Narrow a company-scoped read to one colleague. From custodo_list_members.

limitinteger

Rows to return, 1–100. Default 20.

cursorstring

Opaque cursor from a previous call’s nextCursor, to continue.

response_format'concise' | 'detailed'

concise (default) returns the fields you need to answer a question; detailed adds related records and costs more context.

Headers

X-Tenant-Idstring uuid

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.

oktrue required

Changes

No recorded changes to this operation across all 1 revision of this API.