/v1/facilities/{facility_id}/reportsAuthentication
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/facilities/<FACILITY_ID>/reports' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
facility_idpath · string | stringrequiredFormat: uuid
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": {
"limits": {
"max_period_days": 0,
"max_recipients": 0,
"max_rows": 0
},
"cards": [
{
"availability": {
"state": "available",
"lock": {
"code": "string",
"label": "string",
"message": "string",
"type": "step"
},
"locks": [
{
"code": "string",
"label": "string",
"message": "string",
"type": "step"
}
]
},
"category": "string",
"contains_personal_data": false,
"description": "string",
"key": "string",
"name": "string",
"permission": {
"key": "string",
"label": "string"
},
"schedulable": false,
"scope": "facility",
"user": {
"favorite": false,
"run_count": 0,
"last_run_at": "2026-10-29T12:00:00Z"
},
"advisories": [
{
"code": "string",
"message": "string"
}
],
"coverage": {
"family": "string",
"from": "2026-10-29",
"snapshot_from": "2026-10-29"
}
}
],
"categories": [
{
"key": "string",
"label": "string"
}
],
"features": {}
},
"meta": {
"request_id": "string"
}
}application/json
dataReportCatalogResponserequiredThe report library for one scope (framework 11.3): every card and view, locked ones included.
Show data schema
cardsCardResponse[]Every card, in group order.
Show cards schema
advisoriesAdvisoryResponse[]Each advisory that applies at the facility or facilities asked for.
Show advisories schema
codestringrequired`import_maintained`, `not_cut_over`, `delinquency_not_activated`, `coverage_pending` or `history_not_built`.
messagestringrequiredThe advisory's fixed sentence. It names no facility.
availabilityReportAvailabilityResponserequiredWhether a card or a view can run, and every lock that stands in the way (framework 11.3).
Show availability schema
lockLockResponse | nullThe first applicable lock, the one the page shows.
Show lock schema
LockResponse | nullThe first applicable lock, the one the page shows.
Variant 1: LockResponse
Variant 2: null
locksLockResponse[]The other applicable locks, in order: step, plan, permission.
Show locks schema
codestringrequiredWhat a client keys on: a capability key or `builder_pending` for a step lock, `plan_gate_<feature>` for a plan lock, the card's permission for a permission lock.
labelstringrequiredA short name for what is missing.
messagestringrequiredOne sentence for the reader. It names no facility.
typestringrequired`step`: a capability Facily has not shipped, or a report not built yet. `plan`: the organization's plan lacks the feature. `permission`: the caller may not run it at this scope. Locks are evaluated and listed in that order.
Values: "step", "plan", "permission"
statestringrequired`available`; `available_locked_columns`, which runs without its locked columns and rows; or `locked`. A card is locked when it is, or when every one of its views is.
Values: "available", "available_locked_columns", "locked"
categorystringrequiredThe key of its group.
contains_personal_databooleanrequiredTrue when a column of the card is personal or restricted.
coverageReportCoverageResponse | nullHow far back its history goes; null for a card bounded by no family.
Show coverage schema
ReportCoverageResponse | nullHow far back its history goes; null for a card bounded by no family.
Variant 1: ReportCoverageResponse
familystringrequiredThe coverage family that bounds the card.
fromstring | nullThe family's floor: the first date it holds data for. For all facilities, the earliest floor among them. Null when no facility in scope has data for it.
Format: date
snapshot_fromstring | nullA second bound the catalog service gives for some cards; null when it gives none.
Format: date
Variant 2: null
nulldescriptionstringrequiredOne sentence on what the card holds.
filtersFilterResponse[]Its filters; empty on a stub.
Show filters schema
defaultstring | nullA single-choice enum filter's starting value, the card's own default for it: the dialog opens the filter on it and offers no 'Any'. Null for every other filter, which starts unset.
Show default schema
string | nullA single-choice enum filter's starting value, the card's own default for it: the dialog opens the filter on it and offers no 'Any'. Null for every other filter, which starts unset.
Variant 1: string
Variant 2: null
keystringrequiredThe filter's key in a run's `filters`.
kindstringrequiredHow the dialog renders it and how create validates it.
Values: "enum", "boolean", "date", "number", "money", "entity"
labelstringrequiredThe filter's display name.
maximumstring | nullA number or money filter's inclusive upper bound, as a decimal string.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show maximum schema
string | nullA number or money filter's inclusive upper bound, as a decimal string.
Variant 1: string
Variant 2: null
minimumstring | nullA number or money filter's inclusive lower bound, as a decimal string.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show minimum schema
string | nullA number or money filter's inclusive lower bound, as a decimal string.
Variant 1: string
Variant 2: null
multiplebooleanrequiredAn enum or entity filter that takes a list.
optionsobject[][]An enum filter's choices, as `[value, label]` pairs.
Show options schema
object[]sourcestring | nullAn entity filter's picker.
Values: "unit_type", "unit_group", "unit", "tenant", "lease", "promotion", "insurance_plan", "revenue_rule", "rent_raise_batch", "delinquency_case"
Show source schema
string | nullAn entity filter's picker.
Variant 1: string
Variant 2: null
formatsstring[]The file formats a run of the card produces.
Show formats schema
stringValues: "csv", "xlsx", "pdf", "zip"
keystringrequiredThe card's permanent key.
namestringrequiredThe card's name.
permissionReportPermissionResponserequiredThe permission a card needs, with `facility.read`, at the scope it runs for (framework 10.1).
Show permission schema
keystringrequiredThe permission string, for example `report.financial`.
labelstringrequiredIts display name.
schedulablebooleanrequiredWhether the card can ever be scheduled.
scopestringrequired`facility` (one facility or all), `org_only` (all facilities only) or `either`.
Values: "facility", "org_only", "either"
userReportUserStateResponserequiredThe caller's own use of a card (framework 14).
Show user schema
favoritebooleanrequiredTrue when the caller starred the card.
last_run_atstring | nullWhen the caller last created a manual run of the card.
Format: date-time
Show last_run_at schema
string | nullWhen the caller last created a manual run of the card.
Variant 1: string
Variant 2: null
run_countintegerrequiredHow many manual runs of the card, any view, the caller has created.
viewsViewResponse[]Its views; the first is the default.
Show views schema
aliasesstring[]Other names the search box matches.
Show aliases schema
stringavailabilityReportAvailabilityResponserequiredWhether a card or a view can run, and every lock that stands in the way (framework 11.3).
Show availability schema
lockLockResponse | nullThe first applicable lock, the one the page shows.
locksLockResponse[]The other applicable locks, in order: step, plan, permission.
statestringrequired`available`; `available_locked_columns`, which runs without its locked columns and rows; or `locked`. A card is locked when it is, or when every one of its views is.
Values: "available", "available_locked_columns", "locked"
date_basisReportDateBasisResponserequiredThe one date basis a view cuts on (framework 4.4).
Show date_basis schema
keystringrequiredThe basis.
Values: "effective", "posted", "settled", "event", "recorded", "state"
labelstringrequiredIts display name.
fixed_filtersstring[]requiredThe filters this view fixes; the dialog hides them. Each is a key of the card's `filters`, sorted, and a value sent for one is ignored: the view's own value applies.
Show fixed_filters schema
stringhas_restricted_columnsbooleanrequiredTrue when the view prints a restricted column, masked unless the run asks otherwise.
keystringrequiredThe view's permanent key, unique across the library; a run is created for it.
kindstringrequired`as_of`, `period`, `roll` or `tenant_document`: which dates a run of it takes.
Values: "as_of", "period", "roll", "tenant_document"
max_period_daysinteger | nullThe longest period a run accepts; null when the card relies on the row limit.
Show max_period_days schema
integer | nullThe longest period a run accepts; null when the card relies on the row limit.
Variant 1: integer
Variant 2: null
namestringrequiredThe view's name.
storedge_namestring | nullThe name this report had in the management system the organization used before, if any.
Show storedge_name schema
string | nullThe name this report had in the management system the organization used before, if any.
Variant 1: string
Variant 2: null
tablesTableResponse[]Its tables; empty on a stub.
Show tables schema
columnsColumnResponse[]Its columns, in output order.
keystringrequiredThe table's key, the `table` a rows page asks for.
locked_rowsLockedRowResponse[]Its labelled rows that are locked, absent from every output.
titlestringrequiredThe table's title.
categoriesCategoryResponse[]The groups, in display order.
Show categories schema
keystringrequiredThe group's permanent key.
labelstringrequiredThe group's name.
featuresobject`ai_custom_reports`, `drive_delivery` and `scheduling`, each locked or available.
limitsReportLimitsResponserequiredLimits the page states before a run (framework 7.8).
Show limits schema
max_period_daysintegerrequiredThe longest period a card accepts unless it declares its own.
max_recipientsintegerrequiredThe most recipients one schedule may name.
max_rowsintegerrequiredA run with more rows than this is refused, never truncated.
metaMetarequiredEnvelope 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