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

Create Report Run

Reports · REST API reference

Get support
POST/v1/facilities/{facility_id}/report-runs
Create a run of one view for one facility or for `all`; 202 with the run, queued.

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-runs' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "view_key": "<VALUE_MATCHING_PATTERN>",
  "as_of": "2026-10-29",
  "filters": {},
  "idempotency_key": "string",
  "include_restricted": false,
  "notify_me": false,
  "preferred_format": "csv",
  "range": "string"
}'
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

as_ofstring | null

For an as-of view: the date the report describes. Defaults to the day before today at the facility.

Format: date

Show as_of schema
string | null

For an as-of view: the date the report describes. Defaults to the day before today at the facility.

Variant 1: string
string
Variant 2: null
null
filtersobject

The view's filters by key, as the catalog lists them. Money is a decimal string, never a number.

idempotency_keystring | null

A client key. Sent again with the same request it returns the original run; with another request it is refused.

Min length: 1 · Max length: 120

Show idempotency_key schema
string | null

A client key. Sent again with the same request it returns the original run; with another request it is refused.

Variant 1: string
string
Variant 2: null
null
include_restrictedboolean

Store identification numbers and dates of birth unmasked. Needs View tenants at the scope; never available to an API key.

Default: false

notify_meboolean

Email the member a link when the run is ready, or a notice if it fails. Refused while scheduled reports are not available, and for an API key or a Facily staff entry.

Default: false

preferred_formatstring

The file the page opens first: one of the formats the report offers.

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

rangestring | ReportDateRange | null

For a period view: a named range (`today`, `yesterday`, `last-7`, `last-30`, `this-week`, `last-week`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `ytd`, `last-year`), resolved on the server against the facility's local date, or explicit `start` and `end` dates. Omitted for any other view.

Show range schema
string | ReportDateRange | null

For a period view: a named range (`today`, `yesterday`, `last-7`, `last-30`, `this-week`, `last-week`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `ytd`, `last-year`), resolved on the server against the facility's local date, or explicit `start` and `end` dates. Omitted for any other view.

Variant 1: string
string
Variant 2: ReportDateRange
endstringrequired

The last day of the period, inclusive.

Format: date

startstringrequired

The first day of the period, on each facility's own calendar.

Format: date

Variant 3: null
null
view_keystringrequired

The view to run, as the catalog lists it. The report it belongs to is found from it.

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

Responses

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

202Successful Response
JSON · generated example
{
  "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

dataRunResponserequired

One run: its settings, status, notes, files, and the tables it stored with their columns. No figures.

Show data schema
as_ofstring | null

The as-of date, for an as-of report.

Format: date

Show as_of schema
string | null

The as-of date, for an as-of report.

Variant 1: string
string
Variant 2: null
null
card_namestring | null

The report's name.

Show card_name schema
string | null

The report's name.

Variant 1: string
string
Variant 2: null
null
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
string
Variant 2: null
null
contains_personal_databooleanrequired

True when the report holds personal data.

created_atstringrequired

When the run was asked for.

Format: date-time

data_as_ofstring | null

The moment the run's figures describe.

Format: date-time

Show data_as_of schema
string | null

The moment the run's figures describe.

Variant 1: string
string
Variant 2: null
null
date_basisstringrequired

The date the run's view cuts on.

date_basis_labelstringrequired

The run's date basis in words, as the report library and the run's files print it.

definition_keystringrequired

The report's key.

error_codestring | null

Why a failed run failed, as a code.

Show error_code schema
string | null

Why a failed run failed, as a code.

Variant 1: string
string
Variant 2: null
null
error_messagestring | null

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

Show error_message schema
string | null

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

Variant 1: string
string
Variant 2: null
null
exceptions_countinteger | null

Rows listed as tie-out exceptions, once completed.

Show exceptions_count schema
integer | null

Rows listed as tie-out exceptions, once completed.

Variant 1: integer
integer
Variant 2: null
null
expiredbooleanrequired

True once the run's files are no longer offered.

expires_atstring | null

When the run's files stop being offered.

Format: date-time

Show expires_at schema
string | null

When the run's files stop being offered.

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

The facilities a completed run covers, with their codes and names.

Show facilities schema
codestringrequired

The facility's code.

idstringrequired

The facility's id.

Format: uuid

is_activebooleanrequired

False for a facility that was deactivated; its history is still reported.

namestringrequired

The facility's name.

facility_idstring | null

The facility the run covers; null for all facilities.

Format: uuid

Show facility_id schema
string | null

The facility the run covers; null for all facilities.

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

The run's files.

Show files schema
detail_omittedbooleanrequired

True when the file prints the summary without its detail rows.

display_namestring | null

The name the file is saved under, once it is ready.

Show display_name schema
string | null

The name the file is saved under, once it is ready.

Variant 1: string
string
Variant 2: null
null
formatstringrequired

The file's format.

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

messagestring | null

Why a file is unavailable, failed, or prints totals only, for the reader.

Show message schema
string | null

Why a file is unavailable, failed, or prints totals only, for the reader.

Variant 1: string
string
Variant 2: null
null
reasonstring | null

Why a file failed or is unavailable, as a code.

Show reason schema
string | null

Why a file failed or is unavailable, as a code.

Variant 1: string
string
Variant 2: null
null
size_bytesinteger | null

The file's size, once it is ready.

Show size_bytes schema
integer | null

The file's size, once it is ready.

Variant 1: integer
integer
Variant 2: null
null
statusstringrequired

`queued` while it is prepared, `ready` to download, `failed` or `unavailable` when it cannot be.

Values: "queued", "ready", "failed", "unavailable"

filtersobjectrequired

The 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.

idstringrequired

The run's id.

Format: uuid

includes_open_daybooleanrequired

True when the run reaches a day still in progress at a facility.

notesReportRunNoteResponse[]

Notes for the reader.

Show notes schema
codestringrequired

What a client keys on.

columnstring | null

The column the note is about, if one.

Show column schema
string | null

The column the note is about, if one.

Variant 1: string
string
Variant 2: null
null
facility_idstring | null

The facility the note is about, if one.

Format: uuid

Show facility_id schema
string | null

The facility the note is about, if one.

Variant 1: string
string
Variant 2: null
null
messagestringrequired

One sentence for the reader. It holds no tenant value.

period_endstring | null

The last day of the period, for a period report.

Format: date

Show period_end schema
string | null

The last day of the period, for a period report.

Variant 1: string
string
Variant 2: null
null
period_startstring | null

The first day of the period, for a period report.

Format: date

Show period_start schema
string | null

The first day of the period, for a period report.

Variant 1: string
string
Variant 2: null
null
preferred_formatstring | null

The file the run was asked to open first; null when the run stored none.

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

Show preferred_format schema
string | null

The file the run was asked to open first; null when the run stored none.

Variant 1: string
string

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

Variant 2: null
null
range_rulestring | null

The 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 | null

The 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
string
Variant 2: null
null
requested_bystringrequired

The member who asked for the run.

Format: uuid

restrictedbooleanrequired

True when the run stored restricted columns unmasked.

row_countinteger | null

Detail rows the run holds, once completed.

Show row_count schema
integer | null

Detail rows the run holds, once completed.

Variant 1: integer
integer
Variant 2: null
null
scope_facility_idsstring[]

Every facility the run covers, fixed when it was asked for.

Show scope_facility_ids schema
string
started_atstring | null

When the run's build started.

Format: date-time

Show started_at schema
string | null

When the run's build started.

Variant 1: string
string
Variant 2: null
null
statusstringrequired

`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 | null

The date this column is cut on, when not the view's.

Values: "effective", "posted", "settled", "event", "recorded", "state"

Show date_basis schema
string | null

The date this column is cut on, when not the view's.

Variant 1: string
Variant 2: null
headerstringrequired

The header every file prints, with its date basis and any history mark.

keystringrequired

The column's key in the stored rows.

labelstringrequired

The column's name.

legendstring | null

The sentence the files print for this column, if any.

Show legend schema
string | null

The sentence the files print for this column, if any.

Variant 1: string
Variant 2: null
placesintegerrequired

The decimal places of a quantity.

reasonstring | null

Why the verdict is not `observed`, as a code.

Show reason schema
string | null

Why 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"

typestringrequired

The 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.

exceptionsintegerrequired

Rows that broke the table's tie-out and are listed as exceptions.

keystringrequired

The table's key, the `table` a page of rows asks for.

layoutstringrequired

How 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
object
pagesintegerrequired

Pages of rows; each page holds up to 500 lines.

rowsintegerrequired

Lines stored, subtotal and exception lines included.

titlestringrequired

The table's title.

triggerstringrequired

`manual`, or `schedule` for a scheduled run.

Values: "manual", "schedule"

view_keystringrequired

The view's key.

view_namestring | null

The view's name.

Show view_name schema
string | null

The view's name.

Variant 1: string
string
Variant 2: null
null
weakest_verdictstring | null

The least certain history mark, once completed.

Values: "observed", "rebuilt", "approximate", "shallow"

Show weakest_verdict schema
string | null

The least certain history mark, once completed.

Variant 1: string
string

Values: "observed", "rebuilt", "approximate", "shallow"

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 Run | Facily Developers