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

{
  "reportId": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e"
}

{
  "success": true,
  "results": {
    "requestId": "rep_result:12345abc",
    "status": "complete",
    "reportData": {
      "data": [
        [
          "Timeframe",
          "Department",
          "Hired"
        ],
        [
          "Q1 2024",
          "Engineering",
          45
        ],
        [
          "Q1 2024",
          "Sales",
          32
        ],
        [
          "Q2 2024",
          "Engineering",
          52
        ]
      ],
      "columnNames": [
        "Timeframe",
        "Department",
        "Hired"
      ],
      "metadata": {
        "updatedAt": "2024-01-15T10:30:00.000Z",
        "title": "Quarterly Hiring Report",
        "reportGeneratedAt": "2024-01-15T14:25:33.123Z",
        "cacheExpiresAt": "2024-01-15T15:25:33.123Z"
      }
    },
    "failureReason": null
  }
}