Reports

The Reports API provides access to RORCex's library of pre-built analytical reports. Reports can execute synchronously (returning results inline) or asynchronously (returning a run ID for polling). See the async polling guide for the recommended polling pattern.

Reports run against RORCex's synced aggregate store — not a live lane read — so results reflect data as of the last sync from the RORC back office (typically within ~5 minutes), and they remain available even when a lane is offline. See Data Sources & Freshness.

---

List Reports

Return the full catalogue of available reports, including each report's parameter schema and execution metadata.

GET /v1/reports

Authentication: OAuth Token (service_account or user) Permission: rorcex:reports.execute

Response

{
  "reports": [
    {
      "id": "operational.yesterday_close_summary",
      "pack": "operational",
      "name": "Yesterday Close Summary",
      "description": "End-of-day close totals and exceptions for all stores, for yesterday's business day.",
      "parameter_schema": {
        "type": "object",
        "properties": {
          "stores": { "type": "array", "items": { "type": "string" } }
        },
        "required": []
      },
      "execution_mode": "sync",
      "cache_ttl_seconds": 300,
      "freshness_note": "Data reflects the completed close; re-runs within the TTL window return the cached result."
    }
  ]
}

Status: 200 OK

Response Fields

Field	Type	Description
id	string	Report slug — use this as the report_id path parameter in run endpoints
pack	string	Logical grouping: operational, sales, product, or ops
name	string	Human-readable report name
description	string	One-sentence description of what the report produces
parameter_schema	object	JSON Schema describing accepted parameters for POST /v1/reports/{report_id}/run
execution_mode	string	sync (result inline) or async (returns a run ID)
cache_ttl_seconds	integer	How long a completed result is cached before the next run re-executes
freshness_note	string	Human-readable note about data currency and cache behaviour

Registered Reports

Pack	Report ID	Name
operational	operational.yesterday_close_summary	Yesterday Close Summary
operational	operational.sales_pace_today	Sales Pace Today
operational	operational.drift_watchlist	Drift Watchlist
sales	sales.department_performance_by_store	Department Performance by Store
sales	sales.cashier_scorecard_cross_store	Cashier Scorecard Cross-Store
sales	sales.hourly_pace_heatmap	Hourly Pace Heatmap
product	product.retail_variance_cross_store	Retail Variance Cross-Store
product	product.price_change_history	Price Change History
product	product.slow_movers_cross_store	Slow Movers Cross-Store
product	product.catalog_gap_detection	Catalog Gap Detection
ops	ops.refund_void_audit	Refund & Void Audit
ops	ops.inventory_adjustment_audit	Inventory Adjustment Audit
ops	ops.outlier_store_flagging	Outlier Store Flagging

The authoritative list of accepted parameters for each report is its parameter_schema field. Consult the list endpoint for the current schema before constructing a run request.

Errors

See /reference/errors.

---

Run Report

Execute a report. Supply parameters that satisfy the report's parameter_schema. Synchronous reports return results directly; asynchronous reports return a run ID for polling.

POST /v1/reports/{report_id}/run

Authentication: OAuth Token (service_account or user) Permission: rorcex:reports.execute

Path Parameters

Parameter	Type	Required	Description
report_id	string	Yes	Report slug (e.g., sales.department_performance_by_store)

Request Body

The request body is a JSON object whose fields are validated against the target report's parameter_schema. Retrieve the schema from GET /v1/reports before submitting.

{
  "stores": ["org_00000k1L2m3N4o5", "org_00000a1B2c3D4e5"],
  "from": "2026-06-01",
  "to": "2026-06-11"
}

Response — Synchronous (execution_mode: "sync")

{
  "result": {
    "data": [
      { "store_org_id": "org_00000k1L2m3N4o5", "DeptCode": "01", "NetSales": 41820.75 }
    ],
    "source": "cache",
    "generated_at": "2026-06-11T08:00:00Z",
    "params_echo": {
      "stores": ["org_00000k1L2m3N4o5", "org_00000a1B2c3D4e5"],
      "from": "2026-06-01",
      "to": "2026-06-11"
    },
    "freshness_label": "Cached result from 08:00 UTC",
    "warnings": [],
    "cache_hit": true
  }
}

Status: 200 OK

Response Fields — Synchronous

Field	Type	Description
result.data	array	Report rows, in each report's own schema. HQ-aggregate-backed reports return snake_case rows.
result.source	string	live (freshly executed) or cache (served from cache)
result.generated_at	string (ISO 8601)	When this result was generated
result.params_echo	object	The parameters that produced this result
result.freshness_label	string	Human-readable freshness description
result.warnings	array	Non-fatal warnings (e.g., one store returned no data)
result.cache_hit	boolean	true if served from the result cache, false if freshly executed.

Response — Asynchronous (execution_mode: "async")

{
  "run_id": "01J9XS5M8Q9WP3ZR7AC4VHE1XD",
  "status": "pending",
  "poll_url": "/api/v1/reports/runs/01J9XS5M8Q9WP3ZR7AC4VHE1XD",
  "estimated_seconds": 12
}

Status: 202 Accepted

Response Fields — Asynchronous

Field	Type	Description
run_id	string	Public run ID — use with GET /v1/reports/runs/{public_id}
status	string	Initial status: always "pending"
poll_url	string	Convenience URL for polling the run status
estimated_seconds	integer	Estimated time to completion in seconds

See the async polling guide for the recommended polling pattern.

Errors

Status	Error	Description
404	report_not_found	No report matches the given report_id
422	report_param_validation_failed	Body does not satisfy the report's parameter_schema
422	report_failed	Report executed but produced no result

See /reference/errors for error envelope shapes.

---

Get Run Status

Poll the status of an asynchronous report run.

GET /v1/reports/runs/{public_id}

Authentication: OAuth Token (service_account or user) Permission: rorcex:reports.execute

Path Parameters

Parameter	Type	Required	Description
public_id	string	Yes	The run ID returned by POST /v1/reports/{report_id}/run

Response

{
  "run_id": "01J9XS5M8Q9WP3ZR7AC4VHE1XD",
  "report_id": "sales.department_performance_by_store",
  "status": "completed",
  "params_echo": {
    "stores": ["org_00000k1L2m3N4o5"],
    "from": "2026-06-01",
    "to": "2026-06-11"
  },
  "created_at": "2026-06-11T09:00:00Z",
  "started_at": "2026-06-11T09:00:01Z",
  "completed_at": "2026-06-11T09:00:13Z",
  "result": { "data": [], "source": "live", "generated_at": "2026-06-11T09:00:13Z", "params_echo": {}, "freshness_label": "Live result", "warnings": [] },
  "error_class": null,
  "error_message": null
}

Status: 200 OK

Response Fields

Field	Type	Description
run_id	string	Public run ID
report_id	string	Report slug that was executed
status	string	One of: pending, running, completed, errored
params_echo	object	Parameters submitted with the run
created_at	string (ISO 8601)	When the run was enqueued
started_at	string or null (ISO 8601)	When execution began; null if still pending
completed_at	string or null (ISO 8601)	When execution finished; null if not yet complete
result	object or null	Populated when status is completed — same shape as the synchronous result
error_class	string or null	Error class name when status is errored
error_message	string or null	Human-readable error description when status is errored

Only runs belonging to the requesting organization are visible. Attempting to poll a run from another organization returns 404.

Errors

See /reference/errors.

---

Get Run Result

Retrieve the completed result for a run directly, without the run metadata envelope.

GET /v1/reports/runs/{public_id}/result

Authentication: OAuth Token (service_account or user) Permission: rorcex:reports.execute

Path Parameters

Parameter	Type	Required	Description
public_id	string	Yes	The run ID

Response

{
  "result": {
    "data": [
      { "store_org_id": "org_00000k1L2m3N4o5", "DeptCode": "01", "NetSales": 41820.75 }
    ],
    "source": "live",
    "generated_at": "2026-06-11T09:00:13Z",
    "params_echo": {},
    "freshness_label": "Live result",
    "warnings": []
  }
}

Status: 200 OK

Returns 404 when the run does not exist, is not yet complete, or belongs to a different organization.

Errors

See /reference/errors.