Skip to main content

Setting up a Report Schedule job using the Bright Analytics API

How to configure a Report Schedule job to fetch data from the Bright Analytics Reporting API

Overview

Report Schedule jobs can fetch data from the Bright Analytics Reporting API instead of running a SQL query. This is useful when you want to export data directly from the BA data model without writing custom SQL.

When the target option ba_report_spec is set, the job will POST a report specification to the BA API and write the results to a file for upload — everything else (file naming, upload to sFTP or S3, encoding) works exactly as normal.

1. Connection setup

The API credentials must be stored in the connection options (not job options). Connection options are encrypted at rest, which is required for a Bearer token.

Add the following two options to the connection assigned to the job:

Option key

Value

ba_api_token

The Bearer token for the BA Reporting API

ba_tenant_api

The tenant API ID (e.g. TCXHJHT2)

If either value is missing the job will fail immediately with a descriptive log message.

2. Target configuration

On the target, set ba_report_spec to the report specification as a JSON string. This defines the metrics, dimensions, and filters for the report. Do not include start or end date fields in the spec — these are always injected automatically from the job's date context.

All the usual file options still apply:

Option key

Notes

ba_report_spec

JSON string — metrics, dimensions and filters. No dates needed.

date_range

Optional. Named range label (e.g. last_7_days). If not set, defaults to the job's grain date.

file_extension

e.g. .csv

output_delimiter

Defaults to ,

output_enclosure

Optional. Character to wrap field values in.

write_column_headers

Set to any value to write a header row using the column names returned by the API.

upload_encoding

Optional. e.g. ISO-8859-1

3. Report spec format

The spec follows the BA Reporting API format. Only include metrics, dimensions, and filters — the date range is handled by the job:

{
  "metric_ids": [56],
  "dimension_ids": [1, 33],
  "dimension_filters": [
    {
      "dimension_id": 33,
      "type": "in",
      "values": ["Paid Search", "Paid Social", "Display"]
    }
  ]
}

Use the BA data model to find the correct metric and dimension IDs.

4. Date range

The start and end fields are automatically injected into the spec at runtime — you never need to put them in the spec JSON.

  • If date_range is not set, both start and end are set to the job's grain date (single-day run).

  • If date_range is set to a named range label, the corresponding start and end dates are used — the same labels supported by the Facebook feed.

The resolved date range is written to the process log for every run.

5. Column headers

Unlike the SQL path (which uses a UNION trick to inject a header row), the API path can write headers automatically. Set the write_column_headers target option to get a header row written from the column names returned by the API.

Notes

  • The API returns all rows in a single response — there is no chunked/paginated fetching as with SQL queries.

  • The target_custom SQL field is ignored when ba_report_spec is set.

  • The job still requires a connection to be set — this is where the API credentials live, as well as the upload destination (sFTP, S3, etc.).

Did this answer your question?