---
title: "report.synchronous"
method: POST
path: "/report.synchronous"
tags: ["Report"]
---

# report.synchronous

`POST /report.synchronous`

> Beta
>
> This endpoint is currently in beta and may change without notice.

Retrieves report data synchronously.

**Timeout:** 30 seconds. If a report is timing out, use the asynchronous `report.generate` instead.

**Result Style (`resultStyle`):**
- `inline` (default): completed report data is embedded in the response under `reportData`.
- `url`: for a completed report, `reportData` contains `url` (a short-lived presigned S3 download URL) and `metadata` instead of the inline `data`/`columnNames`. Use this to download large reports directly from S3 instead of through the API. `includeHeadersInData` must be `true` (or omitted) when `resultStyle` is `url`.
- The presigned download is served with `Content-Encoding: br` (Brotli) and no content negotiation, so the client fetching `reportData.url` must decode Brotli. Browsers, `node-fetch`, `curl` installed from `brew`, and Python `requests` with the `brotli`/`brotlicffi` package decode it automatically; stock macOS `curl` and a bare `pip install requests` do not.
- For "Show All" reports whose result is a single aggregate count, the response falls back to `inline`: `reportData` contains `data`/`columnNames` and no `url`. Detect the fallback by checking for `reportData.data` with no `reportData.url`. Report types that are not supported by the public API continue to return the standard "not supported" error rather than falling back.

**Rate Limiting (Per Organization):**
- **Request limit**: 15 requests per minute per organization.
- **Concurrent limit**: Maximum 3 report operations at once per organization (shared with `report.generate`).
- Rate limits are shared with `report.generate` for starting new generations.

**Usage Notes:**
- If you receive a 429 error, your organization has hit its limit - wait briefly and retry.
- For long-running reports, use `report.generate` for async processing.
- Concurrent limit is released when the HTTP request completes.

**Requires the [`reportsRead`](authentication#permissions-reportsynchronous) permission.**

## Request body

- ReportSynchronousRequest
  - `reportId` string, uuid, required — The ID of the report
  - `includeHeadersInData` boolean, nullable — When true (default), column headers are included as the first row in the data array. When false, headers are only in the columnNames property.
  - `resultStyle` 'inline' | 'url', nullable — How completed report data is returned. "inline" (default) embeds the data in the response; "url" returns a short-lived presigned S3 download URL instead. Requires includeHeadersInData to be true (or omitted) when "url".

## Response `200`

Responses from the report.synchronous endpoint

- union
  - ReportSynchronousSuccessResponse
    - `success` true, required
    - `results` ReportBuildStatus, required
      - `requestId` string, required — Unique identifier for this report generation request
      - `status` 'requested' | 'in_progress' | 'complete' | 'failed', required — Current status of the report generation
      - `reportData` union, required — Report data. Only present when status is complete. Contains inline `data`/`columnNames` when resultStyle is "inline" (the default, and the fallback for "url" when the cached result is in the legacy inline format), or `url` plus `metadata` when resultStyle is "url".
        - ReportData
          - `data` array[], required — Report data rows as arrays of values. When includeHeadersInData is true (default), the first row contains column headers.
            - union[]
              - …
          - `columnNames` string[], required — Column names/headers for the report data.
          - `metadata` object, required — Metadata describing the generated report data.
            - `updatedAt` string, date-time, required — When the report data was last updated
            - `title` string, required — Report title
            - `reportGeneratedAt` string, date-time, nullable — ISO 8601 timestamp indicating when the report data was generated. Only present when status is complete.
            - `cacheExpiresAt` string, date-time, nullable — ISO 8601 timestamp indicating when the cached report data will expire. Only present when status is complete or failed.
        - UrlReportData
          - `url` string, uri, required — Presigned S3 URL to download the completed report data directly. The downloaded body is brotli-compressed JSON of the form `{ data, columnNames, metadata }` — the same shape as inline `reportData`, with column headers as the first row of `data`, except `metadata` carries only `updatedAt` and `title`. Clients must support brotli (Content-Encoding: br) decompression.
          - `metadata` object, required — Metadata describing the generated report data.
            - `updatedAt` string, date-time, required — When the report data was last updated
            - `title` string, required — Report title
            - `reportGeneratedAt` string, date-time, nullable — ISO 8601 timestamp indicating when the report data was generated. Only present when status is complete.
            - `cacheExpiresAt` string, date-time, nullable — ISO 8601 timestamp indicating when the cached report data will expire. Only present when status is complete or failed.
      - `failureReason` string, nullable — Error information if report generation failed.
  - ErrorResponse
    - `success` false, required
    - `errors` ErrorDetail[], required
      - `message` string, required
      - `parameter` string

---

[API](https://skmtc.net/ashbyhq/apis/ashby-api.md) · [All operations](https://skmtc.net/ashbyhq/apis/ashby-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ashbyhq/ashby-api/revisions/778b919dc743/schema)