Skip to main content

What are Data Exports?

Data Exports let you export your Northbeam data to your own cloud storage (GCS or S3) via the API. Data Exports is the parent surface — the same as the Data Exports tab in the app — and it can run several different report types. Every report shares the same setup (authentication, destinations, and result polling); each report type then has its own creation endpoint and options.

Report types

The rest of this page covers the setup that is common to all report types.

Authentication

Every request needs an API key and your client id, sent as headers. Generate a key by following the Authentication guide. The examples in each report’s guide show how to pass the Authorization and Data-Client-ID headers.

Destinations

Exports are written to a cloud storage bucket you own. Provide the destination in the create request of whichever report you’re running:
  • GCS — pass bucket_name. See Exporting to GCS for how to grant Northbeam write access.
  • S3 — pass bucket_name plus aws_role (an IAM role ARN with write access) and region. See Exporting to S3.
The destination fields are the same across report types.

Fetching your export results

Creating any export returns an id. Exports run asynchronously, so poll the shared results endpoint with that id until it finishes — this endpoint is the same for every report type.
The response status field has three possible values: While processing (PENDING):
When complete (SUCCESS):
Important: exports can take anywhere from a few seconds to several minutes, and a 200 OK does not mean the export is ready. Keep polling only while status is "PENDING"; on "SUCCESS" download the file from the link in result (the link is only valid for a limited time, so re-request it if it expires); on "ERROR" stop polling and submit a new export. The only supported format today is CSV.

Checking data processing status

An export reflects your data as of its last processing run. To check how fresh your data is before exporting, call Fetch data processing status. It returns when your data last finished processing (last_processed_at) and when the next run is estimated to finish (estimated_next_processed_at), the same times shown at the top of the Northbeam dashboard. Both are in UTC, and either can be null.

Rate limits

The result endpoint and the discovery endpoints can each be called up to 100 requests/second, and the processing status endpoint up to 60 requests/minute. See Rate Limits for the full table.