/v1/report-schedules/{schedule_id}Authentication
Bearer API key or Facily session, subject to permissions and facility scope.
Authentication and scopeRequest 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 --request PATCH \
--url 'https://api.staging.facily.ai/v1/report-schedules/<SCHEDULE_ID>' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"action": "string",
"cadence": "daily",
"filters": {},
"format": "csv",
"local_time": "<VALUE_MATCHING_PATTERN>",
"month_day": 0,
"notes": "string",
"range": "string",
"recipient_user_ids": [
"00000000-0000-4000-8000-000000000001"
],
"starts_on": "2026-10-29",
"weekday": 1
}'Parameters
schedule_idpath · stringrequiredThe report schedule's id.
Format: uuid
Request body
application/json · Required
ReportScheduleEditRequest | ReportSchedulePauseRequest | ReportScheduleResumeRequest | ReportScheduleTakeOverRequestVariant 1: ReportScheduleEditRequest
actionstringrequired`edit`.
cadencestring | nullHow often it runs.
Values: "daily", "weekly", "monthly", "quarterly"
Show cadence schema
string | nullHow often it runs.
Variant 1: string
stringValues: "daily", "weekly", "monthly", "quarterly"
Variant 2: null
nullfiltersobject | nullThe view's filters, replacing the stored ones.
Show filters schema
object | nullThe view's filters, replacing the stored ones.
Variant 1: object
objectVariant 2: null
nullformatstring | nullThe file the emailed link opens first.
Values: "csv", "xlsx", "pdf", "zip"
Show format schema
string | nullThe file the emailed link opens first.
Variant 1: string
stringValues: "csv", "xlsx", "pdf", "zip"
Variant 2: null
nulllocal_timestring | null`HH:MM`, local.
Pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Show local_time schema
string | null`HH:MM`, local.
Variant 1: string
stringVariant 2: null
nullmonth_dayinteger | null1 to 28 or -1, monthly and quarterly only; null otherwise.
Show month_day schema
integer | null1 to 28 or -1, monthly and quarterly only; null otherwise.
Variant 1: integer
integerVariant 2: null
nullnotesstring | nullNotes, or null for none.
Max length: 500
Show notes schema
string | nullNotes, or null for none.
Variant 1: string
stringVariant 2: null
nullrangestring | nullA named range, or null for the cadence's default again.
Show range schema
string | nullA named range, or null for the cadence's default again.
Variant 1: string
stringVariant 2: null
nullrecipient_user_idsstring[] | nullUp to 25 members, replacing the stored recipients.
Max items: 25
Show recipient_user_ids schema
string[] | nullUp to 25 members, replacing the stored recipients.
Variant 1: string[]
string[]Variant 2: null
nullstarts_onstring | nullNo run happens before this day.
Format: date
Show starts_on schema
string | nullNo run happens before this day.
Variant 1: string
stringVariant 2: null
nullweekdayinteger | null1 (Monday) to 7 (Sunday), weekly only; null otherwise.
Minimum: 1 · Maximum: 7
Show weekday schema
integer | null1 (Monday) to 7 (Sunday), weekly only; null otherwise.
Variant 1: integer
integerVariant 2: null
nullVariant 2: ReportSchedulePauseRequest
actionstringrequired`pause`.
Variant 3: ReportScheduleResumeRequest
actionstringrequired`resume`.
Variant 4: ReportScheduleTakeOverRequest
actionstringrequired`take_over`.
recipient_user_idsstring[] | nullUp to 25 members replacing the recipients; omitted, the stored ones are kept. Either is checked.
Max items: 25
Show recipient_user_ids schema
string[] | nullUp to 25 members replacing the recipients; omitted, the stored ones are kept. Either is checked.
Variant 1: string[]
string[]Variant 2: null
nullResponses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"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
dataReportScheduleResponserequiredOne schedule (framework 12.1): what it runs, when, for whom, and what the caller may do with it.
Show data schema
cadencestringrequiredHow often it runs.
Values: "daily", "weekly", "monthly", "quarterly"
can_managebooleanrequiredWhether the caller may edit, pause, resume or end it.
can_take_overbooleanrequiredWhether the caller may take it over.
card_namestring | nullThe report's name; null for a report retired since.
Show card_name schema
string | nullThe report's name; null for a report retired since.
Variant 1: string
stringVariant 2: null
nullconsecutive_failuresintegerrequiredFailed runs in a row.
created_atstringrequiredWhen the schedule was created.
Format: date-time
definition_keystringrequiredThe report's key.
facility_idstring | nullThe facility; null for all facilities.
Format: uuid
Show facility_id schema
string | nullThe facility; null for all facilities.
Variant 1: string
stringVariant 2: null
nullfacility_namestring | nullThe facility's name; null for all facilities.
Show facility_name schema
string | nullThe facility's name; null for all facilities.
Variant 1: string
stringVariant 2: null
nullfiltersobjectThe view's filters, as stored.
formatstringrequiredThe file the emailed link opens first.
Values: "csv", "xlsx", "pdf", "zip"
idstringrequiredThe schedule's id.
Format: uuid
last_runReportScheduleLastRunResponse | nullThe most recent run; null before the first.
Show last_run schema
ReportScheduleLastRunResponse | nullThe most recent run; null before the first.
Variant 1: ReportScheduleLastRunResponse
completed_atstring | nullWhen the run completed or failed.
Format: date-time
Show completed_at schema
string | nullWhen the run completed or failed.
Variant 1: string
Variant 2: null
error_messagestring | nullWhy the run failed, for the reader. It holds no value.
Show error_message schema
string | nullWhy the run failed, for the reader. It holds no value.
Variant 1: string
Variant 2: null
idstringrequiredThe run's id.
Format: uuid
statusstringrequired`queued`, `running`, `completed` or `failed`.
Values: "queued", "running", "completed", "failed"
Variant 2: null
nulllocal_timestringrequired`HH:MM` in `timezone`.
month_dayinteger | null1 to 28, or -1 for the last day, for a monthly or quarterly one.
Show month_day schema
integer | null1 to 28, or -1 for the last day, for a monthly or quarterly one.
Variant 1: integer
integerVariant 2: null
nullneeds_ownerbooleanrequiredTrue when the owner can no longer run this report here: a member may take it over.
next_run_atstringrequiredThe next run's moment, in UTC.
Format: date-time
next_run_localstringrequiredThe next run's date and time in `timezone`, ISO with no offset (`2026-11-02T06:00:00`).
notesstring | nullNotes for the members.
Show notes schema
string | nullNotes for the members.
Variant 1: string
stringVariant 2: null
nullownerReportMemberResponserequiredA 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_namestringrequiredThe member's name, as the team list shows it.
idstringrequiredThe member's user id.
Format: uuid
pause_reasonstring | nullWhy 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 | nullWhy 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
stringValues: "manual", "no_recipients", "report_locked", "failing"
Variant 2: null
nullrange_rulestring | nullThe named range each run reports; null for a view that takes no dates.
Show range_rule schema
string | nullThe named range each run reports; null for a view that takes no dates.
Variant 1: string
stringVariant 2: null
nullrecipientsReportMemberResponse[]Who receives the link.
Show recipients schema
display_namestringrequiredThe member's name, as the team list shows it.
idstringrequiredThe member's user id.
Format: uuid
starts_onstringrequiredNo run happens before this day.
Format: date
statusstringrequired`active` or `paused`.
Values: "active", "paused"
timezonestringrequiredThe schedule's timezone: its facility's, or for all the first facility's.
updated_atstringrequiredWhen it last changed.
Format: date-time
view_keystringrequiredThe view's key.
view_namestring | nullThe view's name; null for a view retired since.
Show view_name schema
string | nullThe view's name; null for a view retired since.
Variant 1: string
stringVariant 2: null
nullweekdayinteger | null1 (Monday) to 7 (Sunday) for a weekly schedule.
Show weekday schema
integer | null1 (Monday) to 7 (Sunday) for a weekly schedule.
Variant 1: integer
integerVariant 2: null
nullmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired400Validation error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired401Unauthenticated
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired403Permission denied
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired404Not found
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired409Business logic error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired503Temporary failure
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired