š§¢ Coach T's Recap
This guide takes you from generating an API key to your first successful data pull. It's written for developers, data teams, agencies, and other technical users integrating with the Tracksuit API.
Want to try it in the browser first? Our interactive API documentation lets you paste in your API key, fill in parameters and run live test requests against every endpoint ā plus copy ready-made code snippets and download the OpenAPI spec. It's the fastest way to see a real response before you write any code.
Before you start, you'll need an API key. See the Authentication guide to generate one. Admin access to your Tracksuit account is required for this step.
Base URL
All requests go to the v2 base URL:
<https://prod.beta.api.gotracksuit.com/v2>
Every endpoint sits under /category-views, every request is a GET, and every request must include your Bearer token (see Authentication guide).
Step 1: Find your category views
A category view is a single brand tracked within a specific category and geography. (In the v1 API this was called an "account brand".) Every other endpoint needs a category view ID, so listing them is always your first call.
curl <https://prod.beta.api.gotracksuit.com/v2/category-views> \ -H "Authorization: Bearer YOUR_API_KEY"
The response lists every category view your key can access, each with an id. Each entry actually contains a few IDs, so grab the right one: the ID you want is the top-level id of the category view itself, not the category ID or the geography ID nested inside it. That category view id is what every other endpoint needs.
Each entry also includes the category and geography names so you can tell which tracker it refers to, which is handy when your key has access to more than one.
Step 2: Get the category view's metadata
Fetching metadata for a category view tells you which dimensions, metrics, brands and channels are available for it. Use the brands collection here to find the brand_ids you can filter by later.
curl <https://prod.beta.api.gotracksuit.com/v2/category-views/{id}> \ -H "Authorization: Bearer YOUR_API_KEY"Step 3: Pull funnel data
This is the most common first pull: awareness, consideration, and preference over time.
curl "<https://prod.beta.api.gotracksuit.com/v2/category-views/{id}/funnel?start_period=2025-01-01&end_period=2025-06-01>" \ -H "Authorization: Bearer YOUR_API_KEY"Required parameters:
start_periodandend_periodā ISO 8601 dates marking an inclusive range.
start_period and end_period must be the first day of a month ā these correspond to wave dates, which are always the 1st. Any other day returns an error.
Useful optional parameters:
smoothingārolling-average window, e.g.3moor1y. Defaults to3mo(matching the dashboard); range is1moā1y.1mogives a single, non-smoothed data point.brand_idsā restrict to specific brands (from the metadatabrandscollection). Returns all brands in the category if omitted.metricsā restrict to specific metrics, e.g.["PROMPTED_AWARENESS", "CONSIDERATION"].filtersā demographic filters as stringified JSON, e.g.["Age:18 to 24"].minimum_indicatorā filter out low-sample data points (see below).
Reading the response
Each data point includes the wave date, the brand, the metric, and:
percentageā a value between 0 and 1 (so0.42= 42%)a sample quality indicator (Insufficient / Directional / Reliable) ā the raw sample size (n=) is not exposed; use the indicator to judge how much to trust a point
Step 4: Handle pagination
Responses use cursor-based pagination. If a response contains a next_token value, there's more data: repeat the same request with next_token set to that value, and keep going until next_token comes back null.
Build pagination handling in from day one, even if your current pulls fit on one page. Funnel timelines across many brands and periods can grow large, and if you don't handle it you may silently only ever read the first page.
Other endpoints
All take the same {id} and date parameters as funnel:
/conversionā conversion rates between funnel stages/statementsā brand imagery statement performance/media-consumptionā media channel consumption for the category/profileā demographic breakdowns of a chosen metric (requires ametricparameter)
Common pitfalls
Don't sum demographic slices.
Weighting is applied dynamically per slice, so adding up individual age groups (the "kitchen sink" approach) won't equal the total. If you want the whole category, pull it with no demographic filter; if you want a specific slice, pull that slice on its own.
Working with AI tools
You can download the OpenAPI spec from the top of the interactive documentation and hand the file directly to Claude (or load it into Postman/Insomnia). If you're using an AI tool to generate calls, remind it to handle pagination ā the next_token pattern is straightforward but easy to skip.