/v1/report-runs/{run_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 GET \
--url 'https://api.staging.facily.ai/v1/report-runs/<RUN_ID>' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
run_idpath · stringrequiredThe report run's id.
Format: uuid
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": {
"contains_personal_data": false,
"created_at": "2026-10-29T12:00:00Z",
"date_basis": "string",
"date_basis_label": "string",
"definition_key": "string",
"expired": false,
"filters": {},
"id": "00000000-0000-4000-8000-000000000001",
"includes_open_day": false,
"requested_by": "00000000-0000-4000-8000-000000000001",
"restricted": false,
"status": "queued",
"trigger": "manual",
"view_key": "string"
},
"meta": {
"request_id": "string"
}
}application/json
dataRunResponserequiredOne run: its settings, status, notes, files, and the tables it stored with their columns. No figures.
Show data schema
as_ofstring | nullThe as-of date, for an as-of report.
Format: date
Show as_of schema
string | nullThe as-of date, for an as-of report.
Variant 1: string
stringVariant 2: null
nullcard_namestring | nullThe report's name.
Show card_name schema
string | nullThe report's name.
Variant 1: string
stringVariant 2: null
nullcompleted_atstring | nullWhen the run completed or failed.
Format: date-time
Show completed_at schema
string | nullWhen the run completed or failed.
Variant 1: string
stringVariant 2: null
nullcontains_personal_databooleanrequiredTrue when the report holds personal data.
created_atstringrequiredWhen the run was asked for.
Format: date-time
data_as_ofstring | nullThe moment the run's figures describe.
Format: date-time
Show data_as_of schema
string | nullThe moment the run's figures describe.
Variant 1: string
stringVariant 2: null
nulldate_basisstringrequiredThe date the run's view cuts on.
date_basis_labelstringrequiredThe run's date basis in words, as the report library and the run's files print it.
definition_keystringrequiredThe report's key.
error_codestring | nullWhy a failed run failed, as a code.
Show error_code schema
string | nullWhy a failed run failed, as a code.
Variant 1: string
stringVariant 2: null
nullerror_messagestring | nullWhy a failed run failed, for the reader. It holds no value.
Show error_message schema
string | nullWhy a failed run failed, for the reader. It holds no value.
Variant 1: string
stringVariant 2: null
nullexceptions_countinteger | nullRows listed as tie-out exceptions, once completed.
Show exceptions_count schema
integer | nullRows listed as tie-out exceptions, once completed.
Variant 1: integer
integerVariant 2: null
nullexpiredbooleanrequiredTrue once the run's files are no longer offered.
expires_atstring | nullWhen the run's files stop being offered.
Format: date-time
Show expires_at schema
string | nullWhen the run's files stop being offered.
Variant 1: string
stringVariant 2: null
nullfacilitiesReportRunFacilityResponse[]The facilities a completed run covers, with their codes and names.
Show facilities schema
codestringrequiredThe facility's code.
idstringrequiredThe facility's id.
Format: uuid
is_activebooleanrequiredFalse for a facility that was deactivated; its history is still reported.
namestringrequiredThe facility's name.
facility_idstring | nullThe facility the run covers; null for all facilities.
Format: uuid
Show facility_id schema
string | nullThe facility the run covers; null for all facilities.
Variant 1: string
stringVariant 2: null
nullfilesReportRunFileResponse[]The run's files.
Show files schema
detail_omittedbooleanrequiredTrue when the file prints the summary without its detail rows.
display_namestring | nullThe name the file is saved under, once it is ready.
Show display_name schema
string | nullThe name the file is saved under, once it is ready.
Variant 1: string
stringVariant 2: null
nullformatstringrequiredThe file's format.
Values: "csv", "xlsx", "pdf", "zip"
messagestring | nullWhy a file is unavailable, failed, or prints totals only, for the reader.
Show message schema
string | nullWhy a file is unavailable, failed, or prints totals only, for the reader.
Variant 1: string
stringVariant 2: null
nullreasonstring | nullWhy a file failed or is unavailable, as a code.
Show reason schema
string | nullWhy a file failed or is unavailable, as a code.
Variant 1: string
stringVariant 2: null
nullsize_bytesinteger | nullThe file's size, once it is ready.
Show size_bytes schema
integer | nullThe file's size, once it is ready.
Variant 1: integer
integerVariant 2: null
nullstatusstringrequired`queued` while it is prepared, `ready` to download, `failed` or `unavailable` when it cannot be.
Values: "queued", "ready", "failed", "unavailable"
filtersobjectrequiredThe filters the run was created with, as validated, a value its view fixes included. Sent back with the run's dates and format, they create the same report again.
idstringrequiredThe run's id.
Format: uuid
includes_open_daybooleanrequiredTrue when the run reaches a day still in progress at a facility.
notesReportRunNoteResponse[]Notes for the reader.
Show notes schema
codestringrequiredWhat a client keys on.
columnstring | nullThe column the note is about, if one.
Show column schema
string | nullThe column the note is about, if one.
Variant 1: string
stringVariant 2: null
nullfacility_idstring | nullThe facility the note is about, if one.
Format: uuid
Show facility_id schema
string | nullThe facility the note is about, if one.
Variant 1: string
stringVariant 2: null
nullmessagestringrequiredOne sentence for the reader. It holds no tenant value.
period_endstring | nullThe last day of the period, for a period report.
Format: date
Show period_end schema
string | nullThe last day of the period, for a period report.
Variant 1: string
stringVariant 2: null
nullperiod_startstring | nullThe first day of the period, for a period report.
Format: date
Show period_start schema
string | nullThe first day of the period, for a period report.
Variant 1: string
stringVariant 2: null
nullpreferred_formatstring | nullThe file the run was asked to open first; null when the run stored none.
Values: "csv", "xlsx", "pdf", "zip"
Show preferred_format schema
string | nullThe file the run was asked to open first; null when the run stored none.
Variant 1: string
stringValues: "csv", "xlsx", "pdf", "zip"
Variant 2: null
nullrange_rulestring | nullThe named range that produced the run's dates, or `yesterday` for an as-of date left to its default; null for explicit dates and for a report with no dates.
Show range_rule schema
string | nullThe named range that produced the run's dates, or `yesterday` for an as-of date left to its default; null for explicit dates and for a report with no dates.
Variant 1: string
stringVariant 2: null
nullrequested_bystringrequiredThe member who asked for the run.
Format: uuid
restrictedbooleanrequiredTrue when the run stored restricted columns unmasked.
row_countinteger | nullDetail rows the run holds, once completed.
Show row_count schema
integer | nullDetail rows the run holds, once completed.
Variant 1: integer
integerVariant 2: null
nullscope_facility_idsstring[]Every facility the run covers, fixed when it was asked for.
Show scope_facility_ids schema
stringstarted_atstring | nullWhen the run's build started.
Format: date-time
Show started_at schema
string | nullWhen the run's build started.
Variant 1: string
stringVariant 2: null
nullstatusstringrequired`queued`, `running`, `completed` or `failed`.
Values: "queued", "running", "completed", "failed"
tablesReportRunTableResponse[]The tables a completed run stored; empty until it completes.
Show tables schema
columnsReportRunColumnResponse[]Its columns, in output order.
Show columns schema
date_basisstring | nullThe date this column is cut on, when not the view's.
Values: "effective", "posted", "settled", "event", "recorded", "state"
Show date_basis schema
string | nullThe date this column is cut on, when not the view's.
Variant 1: string
Variant 2: null
headerstringrequiredThe header every file prints, with its date basis and any history mark.
keystringrequiredThe column's key in the stored rows.
labelstringrequiredThe column's name.
legendstring | nullThe sentence the files print for this column, if any.
Show legend schema
string | nullThe sentence the files print for this column, if any.
Variant 1: string
Variant 2: null
placesintegerrequiredThe decimal places of a quantity.
reasonstring | nullWhy the verdict is not `observed`, as a code.
Show reason schema
string | nullWhy the verdict is not `observed`, as a code.
Variant 1: string
Variant 2: null
sensitivitystringrequired`personal` and `restricted` columns hold personal data.
Values: "none", "personal", "restricted"
timestringrequired`dated`, `current_only` (the value at run time) or `today_only` (left out for a past date).
Values: "dated", "current_only", "today_only"
typestringrequiredThe value type every row writes it as.
Values: "money", "count", "percent", "date", "datetime", "text", "identifier", "phone", "bool"
verdictstringrequired`observed`, `rebuilt`, `approximate`, `shallow` or `unavailable` for the run's dates.
exceptionsintegerrequiredRows that broke the table's tie-out and are listed as exceptions.
keystringrequiredThe table's key, the `table` a page of rows asks for.
layoutstringrequiredHow the table is laid out, for example `table` or `summary`.
locked_rowsobject[]Labelled rows left out because what they need is not available yet.
Show locked_rows schema
objectpagesintegerrequiredPages of rows; each page holds up to 500 lines.
rowsintegerrequiredLines stored, subtotal and exception lines included.
titlestringrequiredThe table's title.
triggerstringrequired`manual`, or `schedule` for a scheduled run.
Values: "manual", "schedule"
view_keystringrequiredThe view's key.
view_namestring | nullThe view's name.
Show view_name schema
string | nullThe view's name.
Variant 1: string
stringVariant 2: null
nullweakest_verdictstring | nullThe least certain history mark, once completed.
Values: "observed", "rebuilt", "approximate", "shallow"
Show weakest_verdict schema
string | nullThe least certain history mark, once completed.
Variant 1: string
stringValues: "observed", "rebuilt", "approximate", "shallow"
Variant 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