---
title: "List recurring series sorted by next expected date, or return one full series by id."
method: GET
path: "/v1/recurring"
---

# List recurring series sorted by next expected date, or return one full series by id.

`GET /v1/recurring`

## Request

- Base URL: `https://api.candor.money`
- URL: `https://api.candor.money/v1/recurring`
- Auth: HTTP bearer

List recurring series sorted overdue first and then by next expected date with candidates last, plus commitment totals over the returned rows, or return one full series by id. Recurring defaults to predictable obligations such as rent, mortgage installments, subscriptions, and memberships. Candidates are uncurated detections and contribute nothing to commitment totals. Active series contribute; stopped and dismissed series are omitted unless requested by status. Transaction cashflow role is separate from schedule status. Preserve existing agent-confirmed placements, including exceptions.

## Query parameters

- `id` string
- `cashflow_role` 'income' | 'expense' | 'transfer' | 'debt_payment' | 'refund' | 'unknown'
- `status` string
- `direction` 'inflow' | 'outflow' | 'neutral'
- `account_identity_id` string
- `due_within` integer
- `limit` integer

## Response `200`

Envelope with recurring items sorted overdue first and then by next expected date with candidates last, plus monthly-equivalent and annual totals over exactly those rows, or one full item with confirmation and evidence when id is supplied.

- ResponseEnvelope
  - `schema_version` string, required
  - `generated_at` string, date-time, required
  - `request_id` string, required
  - `status` 'success' | 'partial_success' | 'action_required' | 'error', required
  - `user_message` string: Optional concise user-safe message the calling agent may adapt.
  - `data_freshness` DataFreshness
    - `balances_last_synced_at` string
    - `coverage` 'complete' | 'partial' | 'stale' | 'unavailable', required
    - `holdings_last_synced_at` string
    - `transactions_last_synced_at` string
  - `metadata` object: Response-level protocol metadata such as package compatibility and workspace opening identity or timing. It is not financial workspace data and must not be treated as attention.
    - `view_url` string, uri: Authenticated dashboard destination related to this response. May open a section rather than reproduce the returned records or filters. Per-record view_url values identify exact supported record views. Use returned URLs instead of constructing paths.
  - `warnings` object[], required
  - `errors` AgentError[], required
    - `code` string, required
    - `expires_at` string
    - `idempotency_key` string: Stable key to reuse when retrying this identical logical operation.
    - `message` string, required
    - `recovery_url` string, uri
    - `required_capability` string
    - `retry_after_seconds` integer: Machine-actionable delay before retrying the identical logical operation.
    - `retryable` boolean, required
    - `suggested_command` string
  - `next_actions` AgentAction[], required
    - `intent` string, required
    - `command` string, required
    - `args` object, required
    - `shell` string, required
  - `action` WorkspaceAction
    - `id` string, required
    - `operation` string, required
    - `reason` string, required
    - `root_action_id` string, required
    - `parent_action_id` string
    - `task_key` string
    - `status` 'started' | 'succeeded' | 'refused' | 'failed', required
    - `created_at` string, date-time, required
    - `completed_at` string, date-time
  - `data` object, nullable, required: Operation-specific result data, or null when the request ends in an error.

## Other responses

- `default`: Structured Candor error envelope with machine-readable codes, recovery guidance, and retry timing when applicable.

---

[API](https://skmtc.dev/candor/apis/candor-api.md) · [All operations](https://skmtc.dev/candor/apis/candor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/candor/apis/candor-api/revisions/6c050f72e956?raw)