How to connect the API to your data warehouse

A data warehouse, Snowflake, BigQuery, Redshift, Databricks, is the most robust home for Tracksuit data. You pull from the API on a schedule, land the results as tables, and every downstream tool (BI dashboards, notebooks, your own models) reads from the warehouse instead of hitting the API directly. This guide shows the end-to-end pattern: extract, load, model, and schedule.

This is the foundation for BI tools. Power BI, Tableau and Looker can’t reliably and directly connect to the Tracksuit API. You can connect the API to your warehouse and then flow the data into your BI dashboard.

Set the data warehouse up first, then see How to connect the API to Power BI or Looker.

👉 Try it in the browser first. Our interactive API documentation lets you paste in your key and run live requests against every endpoint, so you can see the exact response shape before you build a pipeline.

The pattern in four steps

The API is a read-only, paginated REST API. Loading it into a warehouse is a standard ELT job:

Stage	What happens
1. Extract	Call each endpoint with a `GET`, following `next_token` until every page is read.
2. Land	Write the raw JSON to a staging table or object store, untouched.
3. Model	Flatten the JSON into clean, typed tables — one per endpoint.
4. Schedule	Re-run on the wave cadence (monthly) so the warehouse stays current.

What you're loading

The data has a natural dimension-plus-facts shape. A category view (a brand and its competitors tracked in a specific category and geography) is your dimension; each metric endpoint is a fact table keyed by that category view's id.

Endpoint	Suggested table	Grain
`GET /category-views`	`category_views` (dimension)	One row per category view your key can access
`GET /category-views/{id}` (metadata)	`category_view_metadata` (dimension)	Available brands, metrics, dimensions, channels per view
`GET /category-views/{id}/funnel`	`funnel` (fact)	One row per wave × brand × metric
`GET /category-views/{id}/conversion`	`conversion` (fact)	One row per wave × brand × stage transition
`GET /category-views/{id}/statements`	`statements` (fact)	One row per wave × brand × statement
`GET /category-views/{id}/media-consumption`	`media_consumption` (fact)	One row per wave × channel
`GET /category-views/{id}/profile`	`profile` (fact)	One row per wave × brand × demographic slice

For exact field names and types, see the Tracksuit API data dictionary and the endpoint reference.

Step 1: Authenticate and store your key safely

Every request carries a Bearer token. You need admin access on your Tracksuit account to generate one. See How to authenticate the Tracksuit API.

curl <https://prod.beta.api.gotracksuit.com/v2/category-views> \   -H "Authorization: Bearer YOUR_API_KEY"

Never hardcode the key in pipeline code. Store it in your warehouse or orchestrator's secret manager (Snowflake secrets, BigQuery Secret Manager, dbt environment variables, Airflow connections) and read it at runtime.

Step 2: Decide what to extract

Scope the pull before you write it:

Which category views? Call GET /category-views first. Every other endpoint needs a category view id. Use the top-level id of the view, not the nested category or geography IDs.
Which endpoints? Most warehouses start with funnel. Add conversion, statements, media-consumption, and profile as needed.
Which date range? Time-series endpoints take start_period and end_period . ISO 8601 dates that must be the first day of a month (they map to wave dates).

Step 3: Extract every page

Every list response carries a next_token. Loop until it comes back null . Never stop early on a short page. Keep all other parameters identical across pages, and treat the token as opaque. Full detail: How to: Handle pagination.

Step 4: Land raw, then model

Land the untouched JSON first (a VARIANT/JSON staging column), then flatten into typed tables. A funnel fact table, for example, has roughly these columns:

Column	Notes
`category_view_id`	Foreign key to your `category_views` dimension
`wave_date`	The period the data point belongs to (always the 1st of a month)
`brand_id`, `brand_name`	The brand the metric is measured for
`metric`	e.g. `PROMPTED_AWARENESS`, `CONSIDERATION`
`percentage`	A value between 0 and 1 (`0.42` = 42%)
`sample_indicator`	Insufficient / Directional / Reliable — how much to trust the point
`dimensions`	If you have filtered to a demographic slice, the selected demographics are reflected here. Store them in a single column that you can filter on to switch between demographic slices.

Store percentage as a fraction, not a whole number. It arrives between 0 and 1. Format it as a percent in your BI layer, not in the warehouse, so the raw value stays exact.

Don't pre-aggregate demographic slices in the warehouse. Weighting is applied dynamically per slice, so summing age groups won't equal the total. Land each slice as its own row and let consumers pick a slice or the unfiltered total.

Step 5: Schedule refreshes on the wave cadence

Tracksuit data updates wave by wave (monthly), so a daily pull is overkill. A scheduled monthly (or weekly, to be safe) job that re-pulls your date range is enough. See How data freshness & wave timing work.

Stay under the rate limit. The API allows 5 requests per second with a burst of 10. Keep extraction concurrency low and back off on 429. For many category views, a sequential pull comfortably fits. See Tracksuit API rate limits.

Don't persist pagination tokens between runs. Cursors expire after 30 minutes. Each scheduled run starts a fresh pull from page 1, never save a next_token to resume hours later.

Choosing how to build it

Approach	Good when
Scripted ELT (Python + your warehouse's loader, orchestrated by Airflow / dbt / cron)	You have a data team and want full control. The pattern above.
Custom connector (Airbyte / Fivetran custom source, Singer tap)	You already run a managed ingestion stack and want this as one more source.
Low-code / iPaaS (Zapier, Make, n8n)	Smaller pulls without a full data team. See How to: Connect the API with low-code tools.

Common pitfalls

Reading only the first page. Always loop until next_token is null, or you'll silently load partial data.

Treating percentage as a whole number. It's a 0–1 fraction; multiplying or rounding it in the warehouse loses precision.

Summing demographic slices. Dynamic weighting means slices don't add up to the total. See How to filter by demographics.

Hardcoding the API key. Use a secret manager; rotate the key if it leaks.