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

Get Report Run

Reports · REST API reference

Get support
GET/v1/report-runs/{run_id}
One run: settings, status, notes, files, and a completed run's tables with their columns and verdicts. No figures. The access rule is checked now, at the run's stored scope.

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 GET \
  --url 'https://api.staging.facily.ai/v1/report-runs/<RUN_ID>' \
  --header "Authorization: Bearer $FACILY_API_KEY"
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Try a request

Staging · read-only

Explore your organization with a read-only request to staging.

Kept in this tab only. Sent directly to api.staging.facily.ai.

GET

Replace the {placeholders} in the path with your resource IDs.

Response
Your response will appear here.

Parameters

run_idpath · stringrequired

The report run's id.

Format: uuid

Responses

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

200Successful 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

Get Report Run | Facily Developers