---
title: "List the scheduled deliveries"
method: POST
path: "/schedules/list"
tags: ["Schedules"]
---

# List the scheduled deliveries

`POST /schedules/list`

## Request

- Base URL: `https://api.reportingninja.com/v1`
- URL: `https://api.reportingninja.com/v1/schedules/list`
- Auth: HTTP bearer

Returns the scheduled deliveries of the account, or of one report when report_key is sent. A schedule at frequency none is kept and listed: it is a configured delivery that is stopped. A one-off delivery that has been asked for and not sent yet is not listed at all, and neither is the request of a snapshot: the key of a queued snapshot is the `schedule_key` /v1/reports/take-snapshot answered, which 409 ALREADY_QUEUED repeats, and /v1/schedules/delete accepts it even though nothing lists it. Two kinds of schedule this version cannot express are still listed and say so: uses_system_template and conditional_execution_enabled mark the ones /v1/schedules/update refuses to change.

## Request body

- SchedulesListRequest: Which schedules to list.
  - `report_key` string: Only the schedules of this report. When absent, every schedule of the account.

## Response `200`

The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok.

- SchedulesListResponse
  - `status` 'ok', required
  - `data` SchedulesListData, required: The scheduled deliveries, ordered by report. A one-off delivery that is waiting to go out is not one of them.
    - `schedules` Schedule[], required
      - `schedule_key` string, nullable, required: The key that addresses this schedule.
      - `report_key` string, nullable, required: The report that is delivered.
      - `frequency` 'daily' | 'weekly' | 'monthly' | 'none' | 'now', nullable, required: How often the report is sent. `none` is a schedule that is kept and does not deliver; `now` appears only in the answer of a one-off delivery.
      - `frequency_details` string, nullable: The weekday in upper case for `weekly`, and the day of the month as a string from "1" to "31" for `monthly`.
      - `time` string, nullable: Hour of the delivery in the time zone of the account, as HH:00.
      - `recipients_to` string[], required
      - `recipients_cc` string[], required
      - `recipients_bcc` string[], required
      - `report_format` 'pdf' | 'xls' | 'link', nullable: How the report travels: attached as a PDF, attached as a spreadsheet, or as a link in the body.
      - `email_template_key` string, nullable: The email template of the account this delivery uses, or null when it uses none and when it uses the system one.
      - `uses_system_template` boolean, required: True when the delivery is built from the system template in the language of the user, which this version cannot express and cannot update.
      - `format` 'html' | 'plain_text', nullable: Body of the email.
      - `subject` string, nullable
      - `sender` string, nullable: Display name of the sender.
      - `sender_email` string, nullable
      - `reply_to_email` string, nullable
      - `origin` 'app' | 'portal' | 'api', nullable: Where the schedule was created.
      - `user_key` string, nullable: The user the delivery is attributed to.
      - `conditional_execution_enabled` boolean: True when the delivery only goes out if a condition holds. This version cannot express the condition, and refuses to change a schedule that has one.
      - `last_execution_at` string, nullable: When it was last delivered, in UTC.
      - `queued` boolean: True while this delivery is being sent. A schedule cannot be changed or stopped while it is true.
    - `count` integer, required
  - `meta` Meta, required
    - `request_id` string, required: Id of this request, useful when reporting an incident.
    - `timestamp` string, date-time, required: When the answer was built, in UTC.

## Other responses

- `400`: The request was refused before anything was written. INVALID_REQUEST covers the framework refusals of every endpoint (the Content-Type is not application/json, the body could not be read, the body is not valid JSON). The report endpoints add their own: VALIDATION_FAILED with details.problems, UNKNOWN_PARAM with the path of the field the endpoint does not read, and the single-field refusals MISSING_REQUIRED_FIELD, INVALID_VALUE and APPEND_NOT_ALLOWED. The description of each operation lists the ones it emits. Everything else a body can get wrong arrives as an entry of details.problems rather than as the code of the envelope.
- `401`: Invalid or missing Bearer token.
- `404`: A key of the request does not name anything this account owns. NOT_FOUND covers reports, sections, widgets, schedules, portal views, brand templates, email templates and language files; TEMPLATE_NOT_FOUND covers a catalog slug, version or section position that stopped being published between the validation and the write. An entity of another account is reported the same way as one that does not exist.
- `413`: The request body is over 1 MB. The cap is applied before authentication, so this answer is refused without the key being read, and it carries the usual error envelope.
- `429`: A budget was spent. RATE_LIMITED is the per-key read budget (300/minute, 5000/day) or the per-account write budget (60/minute, 1000/day). EMAIL_QUOTA_REACHED is the separate budget of 50 calls per account per day that send email, and its Retry-After points at the next UTC midnight. The Retry-After header gives the seconds until the more restrictive window resets. The X-RateLimit-* headers report the read budget, except on the 429 of a write, where they report the write budget.
- `500`: Internal server error.

---

[API](https://skmtc.dev/reportingninja/apis/reporting-ninja-api.md) · [All operations](https://skmtc.dev/reportingninja/apis/reporting-ninja-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reportingninja/apis/reporting-ninja-api/revisions/13876c71be34?raw)