Skip to main content

The Formulayt Reporting API - Using the Reporting API

The Formulayt Reporting API supports both webhook notifications and polling for report status updates. This allows your systems to monitor report progress and automatically retrieve completed CSV files.

This article explains:

  • Starting a Report

  • Notification endpoints

  • Webhook payloads

  • Polling report status

  • Handling completed and failed jobs

Starting a Report

All report requests follow the same pattern:

  • Method: POST

  • Base URL: https://api.gatedcontent.com/api/v1

  • Path: /reports{reportName}

  • Body: JSON object including:

    • startDate / endDate (where relevant)

    • notificationEndpoint

    • Any additional parameters for the report

For example requests and responses for common reports click HERE

When Your Report is Ready

There are two ways to know when a report is ready.

Recommended: A notification endpoint, such as a webhook, in your own environment

Additionally/alternatively: Polling our status endpoint

Important: The Reporting API requires a notificationEndpoint in every POST request.

If you prefer to rely mostly on polling, you can still point this at an endpoint that simply logs or discards the notifications.

Notification Endpoint (Webhook)

For this, you will need an HTTPS URL that can:

  • Accept a POST request with a Content-Type: application/json

  • Read a JSON body similar to the below

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "complete",
  "reportType": "gateActivity",
  "downloadUrl": "https://api.gatedcontent.com/api/v1/reports/d290f1ee-6c54-4b01-90e6-d701748f0851/download",
  "expiresAt": "2025-01-09T10:01:30Z"
}

When a report finishes, we will POST to your notificationEndpoint.

A successful completion might look like:

POST https://client.example.com/report-callback
Content-Type: application/json
{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "complete",
  "reportType": "gateActivity",
  "downloadUrl": "https://api.gatedcontent.com/api/v1/reports/a8e2c0f1-9d4b-4d73-ae0f-702be1e8f9b0/download",
  "expiresAt": "2025-01-09T10:01:30Z"
}

A failure might look like:

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "failed",
  "reportType": "gateActivity",
  "error": "Query exceeded cost or time limit"
}

The recommended, and typical logic, in your environment would be

  1. Parse the JSON

  2. If the status is complete

    1. Immediately store the downloadUrl and expiresAt

    2. Optionally trigger an automatic download into your data warehouse or reporting system

  3. If the status is failed

    1. Log the error field

    2. Consider alerting your team or retrying with a narrower date range

Polling the Status Endpoint

In addition to receiving webhook notifications, you can actively poll the report status endpoint to track job progress and retrieve the final output when it is ready.

Endpoint

GET https://api.gatedcontent.com/api/v1/reports/{jobId}

Authorization: Bearer YOUR_REPORTING_API_KEY

Replace {jobId} with the ID returned when the job was created.

You’ll get a JSON response with job state and, when ready, the downloadUrl and expiresAt.

Queued / running example

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "running",
  "createdAt": "2025-01-02T10:00:00Z"
}

Completed example

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "complete",
  "createdAt": "2025-01-02T10:00:00Z",
  "completedAt": "2025-01-02T10:01:30Z",
  "downloadUrl": "https://api.gatedcontent.com/api/v1/reports/a8e2c0f1-9d4b-4d73-ae0f-702be1e8f9b0/download",
  "expiresAt": "2025-01-09T10:01:30Z"
}

Polling is particularly useful if you prefer a request-driven workflow or when webhook notifications are not yet configured.

Recommended Polling Strategy

A typical approach is to:

  • Poll the endpoint every 30–60 seconds

  • Continue until the status becomes either complete or failed

  • Stop polling immediately once a terminal state is reached

You can also combine both approaches: rely on polling as a fallback, but prefer webhook notifications when available for faster and more efficient updates.

Downloading Your CSV

Once you have the downloadURL (via notification or polling) you can download the CSV directly.

Example Download Request

GET https://api.gatedcontent.com/api/v1/reports/a8e2c0f1-9d4b-4d73-ae0f-702be1e8f9b0/download

Example Using Curl to Save it to a Disk

curl -L "https://api.gatedcontent.com/api/v1/reports/a8e2c0f1-9d4b-4d73-ae0f-702be1e8f9b0/download

" -o gate_activity_jan.csv

You can also have your integration code stream your report straight into

  • A data warehouse

  • A local database

  • Your own storage

Important: The download link is time-limited and will expire after 7 days. After that time you will need to rerun your report if you need the file again.

Summary

The Reporting API supports both webhook notifications and polling workflows.

  • Webhooks provide automatic completion notifications

  • Polling allows manual status monitoring

  • CSV files are downloaded securely using temporary URLs

This flexibility allows integration with a wide range of systems and workflows.

Did this answer your question?