/v1/report-runsAuthentication
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' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
cursorquery · string | nullThe `cursor` of the previous page; omit it for the first page.
limitquery · integerRuns per page.
Default: 25 · Minimum: 1 · Maximum: 100
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": [
{
"created_at": "2026-10-29T12:00:00Z",
"date_basis": "string",
"definition_key": "string",
"expired": false,
"has_notes": false,
"id": "00000000-0000-4000-8000-000000000001",
"requested_by": "00000000-0000-4000-8000-000000000001",
"restricted": false,
"status": "queued",
"trigger": "manual",
"view_key": "string",
"as_of": "2026-10-29"
}
],
"meta": {
"request_id": "string"
},
"pagination": {
"has_more": false,
"limit": 0,
"cursor": "string",
"total_count": 0
},
"metrics": {
"cards": {},
"computed_at": "2026-10-29T12:00:00Z",
"is_stale": false,
"scope": "facility"
}
}application/json
dataRunListItem[]requiredShow 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
nullcreated_atstringrequiredWhen the run was asked for.
Format: date-time
date_basisstringrequiredThe date the run's view cuts on.
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
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
nullfacility_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"
has_notesbooleanrequiredTrue when the run carries notes for the reader.
idstringrequiredThe run's id.
Format: uuid
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
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
nullstatusstringrequired`queued`, `running`, `completed` or `failed`.
Values: "queued", "running", "completed", "failed"
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 of any column of the run, once completed.
Values: "observed", "rebuilt", "approximate", "shallow"
Show weakest_verdict schema
string | nullThe least certain history mark of any column of the run, once completed.
Variant 1: string
stringValues: "observed", "rebuilt", "approximate", "shallow"
Variant 2: null
nullmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequiredmetricsEmbeddedMetrics | nullShow metrics schema
EmbeddedMetrics | nullVariant 1: EmbeddedMetrics
cardsobjectrequiredcomputed_atstring | nullrequiredFormat: date-time
Show computed_at schema
string | nullVariant 1: string
stringVariant 2: null
nullis_stalebooleanrequiredscopestringrequiredValues: "facility", "portfolio"
Variant 2: null
nullpaginationPaginationBlockrequiredPagination metadata for list responses.
Show pagination schema
cursorstring | nullShow cursor schema
string | nullVariant 1: string
stringVariant 2: null
nullhas_morebooleanrequiredlimitintegerrequiredtotal_countinteger | nullShow total_count schema
integer | nullVariant 1: integer
integerVariant 2: null
null400Validation 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