Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsCreate Report Schedule
Search the full API reference Esc to close

Create Report Schedule

Reports · REST API reference

Get support
POST/v1/facilities/{facility_id}/report-schedules
Schedule one view for one facility or for `all`; 201 with the schedule, owned by the caller.

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request example

Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.

cURL
curl --request POST \
  --url 'https://api.staging.facily.ai/v1/facilities/<FACILITY_ID>/report-schedules' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "cadence": "daily",
  "recipient_user_ids": [
    "00000000-0000-4000-8000-000000000001"
  ],
  "view_key": "<VALUE_MATCHING_PATTERN>",
  "filters": {},
  "format": "csv",
  "local_time": "06:00",
  "month_day": 0,
  "notes": "string",
  "range": "string",
  "starts_on": "2026-10-29",
  "weekday": 1
}'
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Parameters

facility_idpath · string | stringrequired

Format: uuid

Request body

application/json · Required

cadencestringrequired

How often it runs. There is no one-time schedule: generate instead.

Values: "daily", "weekly", "monthly", "quarterly"

filtersobject

The view's filters by key, as on a run. Money is a decimal string, never a number.

formatstring | null

The file the emailed link opens first: one of the report's formats. Defaults to the first.

Values: "csv", "xlsx", "pdf", "zip"

Show format schema
string | null

The file the emailed link opens first: one of the report's formats. Defaults to the first.

Variant 1: string
string

Values: "csv", "xlsx", "pdf", "zip"

Variant 2: null
null
local_timestring

`HH:MM` in the schedule's timezone: its facility's, or for all facilities the first facility's. A run starts up to five minutes after it.

Default: "06:00" · Pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$

month_dayinteger | null

For a monthly or quarterly schedule only, and required there: 1 to 28, or -1 for the month's last day. A quarterly schedule runs on that day of January, April, July and October.

Show month_day schema
integer | null

For a monthly or quarterly schedule only, and required there: 1 to 28, or -1 for the month's last day. A quarterly schedule runs on that day of January, April, July and October.

Variant 1: integer
integer
Variant 2: null
null
notesstring | null

Notes for the members.

Max length: 500

Show notes schema
string | null

Notes for the members.

Variant 1: string
string
Variant 2: null
null
rangestring | null

For a period view: the named range each run reports (`yesterday`, `last-week`, `last-month` and the rest of the run body's names), resolved at each run on each facility's own date. Defaults by cadence: daily `yesterday`, weekly `last-week`, monthly `last-month`, quarterly `last-quarter`. An as-of view takes only `yesterday` (its default) and a roll view none.

Show range schema
string | null

For a period view: the named range each run reports (`yesterday`, `last-week`, `last-month` and the rest of the run body's names), resolved at each run on each facility's own date. Defaults by cadence: daily `yesterday`, weekly `last-week`, monthly `last-month`, quarterly `last-quarter`. An as-of view takes only `yesterday` (its default) and a roll view none.

Variant 1: string
string
Variant 2: null
null
recipient_user_idsstring[]required

Up to 25 members who receive the link, each able to run this report at this scope; the recipients route lists who may be chosen.

Max items: 25

Show recipient_user_ids schema
string
starts_onstring | null

No run happens before this day. Defaults to today at the schedule's facility.

Format: date

Show starts_on schema
string | null

No run happens before this day. Defaults to today at the schedule's facility.

Variant 1: string
string
Variant 2: null
null
view_keystringrequired

The view to schedule, as the catalog lists it: a view of a card that can be scheduled and is not locked. The card, the view and the facility are fixed once created.

Min length: 1 · Max length: 80 · Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

weekdayinteger | null

For a weekly schedule only, and required there: 1 is Monday and 7 is Sunday.

Minimum: 1 · Maximum: 7

Show weekday schema
integer | null

For a weekly schedule only, and required there: 1 is Monday and 7 is Sunday.

Variant 1: integer
integer
Variant 2: null
null

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

201Successful Response
JSON · generated example
{
  "data": {
    "cadence": "daily",
    "can_manage": false,
    "can_take_over": false,
    "consecutive_failures": 0,
    "created_at": "2026-10-29T12:00:00Z",
    "definition_key": "string",
    "format": "csv",
    "id": "00000000-0000-4000-8000-000000000001",
    "local_time": "string",
    "needs_owner": false,
    "next_run_at": "2026-10-29T12:00:00Z",
    "next_run_local": "string",
    "owner": {
      "display_name": "string",
      "id": "00000000-0000-4000-8000-000000000001"
    },
    "starts_on": "2026-10-29",
    "status": "active",
    "timezone": "string",
    "updated_at": "2026-10-29T12:00:00Z",
    "view_key": "string"
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

dataReportScheduleResponserequired

One schedule (framework 12.1): what it runs, when, for whom, and what the caller may do with it.

Show data schema
cadencestringrequired

How often it runs.

Values: "daily", "weekly", "monthly", "quarterly"

can_managebooleanrequired

Whether the caller may edit, pause, resume or end it.

can_take_overbooleanrequired

Whether the caller may take it over.

card_namestring | null

The report's name; null for a report retired since.

Show card_name schema
string | null

The report's name; null for a report retired since.

Variant 1: string
string
Variant 2: null
null
consecutive_failuresintegerrequired

Failed runs in a row.

created_atstringrequired

When the schedule was created.

Format: date-time

definition_keystringrequired

The report's key.

facility_idstring | null

The facility; null for all facilities.

Format: uuid

Show facility_id schema
string | null

The facility; null for all facilities.

Variant 1: string
string
Variant 2: null
null
facility_namestring | null

The facility's name; null for all facilities.

Show facility_name schema
string | null

The facility's name; null for all facilities.

Variant 1: string
string
Variant 2: null
null
filtersobject

The view's filters, as stored.

formatstringrequired

The file the emailed link opens first.

Values: "csv", "xlsx", "pdf", "zip"

idstringrequired

The schedule's id.

Format: uuid

last_runReportScheduleLastRunResponse | null

The most recent run; null before the first.

Show last_run schema
ReportScheduleLastRunResponse | null

The most recent run; null before the first.

Variant 1: ReportScheduleLastRunResponse
completed_atstring | null

When the run completed or failed.

Format: date-time

Show completed_at schema
string | null

When the run completed or failed.

Variant 1: string
Variant 2: null
error_messagestring | null

Why the run failed, for the reader. It holds no value.

Show error_message schema
string | null

Why the run failed, for the reader. It holds no value.

Variant 1: string
Variant 2: null
idstringrequired

The run's id.

Format: uuid

statusstringrequired

`queued`, `running`, `completed` or `failed`.

Values: "queued", "running", "completed", "failed"

Variant 2: null
null
local_timestringrequired

`HH:MM` in `timezone`.

month_dayinteger | null

1 to 28, or -1 for the last day, for a monthly or quarterly one.

Show month_day schema
integer | null

1 to 28, or -1 for the last day, for a monthly or quarterly one.

Variant 1: integer
integer
Variant 2: null
null
needs_ownerbooleanrequired

True when the owner can no longer run this report here: a member may take it over.

next_run_atstringrequired

The next run's moment, in UTC.

Format: date-time

next_run_localstringrequired

The next run's date and time in `timezone`, ISO with no offset (`2026-11-02T06:00:00`).

notesstring | null

Notes for the members.

Show notes schema
string | null

Notes for the members.

Variant 1: string
string
Variant 2: null
null
ownerReportMemberResponserequired

A member of the organization as the schedule routes name one: id and display name only, never an address or a role (framework 12.1).

Show owner schema
display_namestringrequired

The member's name, as the team list shows it.

idstringrequired

The member's user id.

Format: uuid

pause_reasonstring | null

Why a paused schedule is paused: `manual`, `no_recipients` (no recipient could receive it), `report_locked` (the report became unavailable) or `failing` (three failed runs in a row).

Values: "manual", "no_recipients", "report_locked", "failing"

Show pause_reason schema
string | null

Why a paused schedule is paused: `manual`, `no_recipients` (no recipient could receive it), `report_locked` (the report became unavailable) or `failing` (three failed runs in a row).

Variant 1: string
string

Values: "manual", "no_recipients", "report_locked", "failing"

Variant 2: null
null
range_rulestring | null

The named range each run reports; null for a view that takes no dates.

Show range_rule schema
string | null

The named range each run reports; null for a view that takes no dates.

Variant 1: string
string
Variant 2: null
null
recipientsReportMemberResponse[]

Who receives the link.

Show recipients schema
display_namestringrequired

The member's name, as the team list shows it.

idstringrequired

The member's user id.

Format: uuid

starts_onstringrequired

No run happens before this day.

Format: date

statusstringrequired

`active` or `paused`.

Values: "active", "paused"

timezonestringrequired

The schedule's timezone: its facility's, or for all the first facility's.

updated_atstringrequired

When it last changed.

Format: date-time

view_keystringrequired

The view's key.

view_namestring | null

The view's name; null for a view retired since.

Show view_name schema
string | null

The view's name; null for a view retired since.

Variant 1: string
string
Variant 2: null
null
weekdayinteger | null

1 (Monday) to 7 (Sunday) for a weekly schedule.

Show weekday schema
integer | null

1 (Monday) to 7 (Sunday) for a weekly schedule.

Variant 1: integer
integer
Variant 2: null
null
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Continue exploringAll reports operations
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

Create Report Schedule | Facily Developers