How do I get an API key and pull my TrueROAS data?
Generate an API key on the API Access page and send it with your store ID to pull spend, sales and ROAS per channel into your own tools.
Open API Access
- Open Setup in the left menu and click Integrations.
- Under API Access (Connect external tools to your TrueROAS data), click Manage on the TrueROAS API card.
- The API Access page opens.
On the Basic plan the page is locked behind a box titled API Access. See Why is a page locked behind Upgrade to Pro?.
Generate your API key
- Under API Key, click Generate API Key. You see API key generated.
- The key shows in the field with its middle hidden.
- Click the copy icon at the right end of the field (tooltip Copy full key) to copy the whole key. The tooltip changes to Copied! and you see Copied to clipboard.
The key starts with trueroas_. It stays on the page, so you can come back and copy it again at any time.
Ask for your data
The How to Use box on the page shows a ready example that already contains the ID of the store you have selected. The example below is the same request with a date range added. Replace YOUR_API_KEY with your key:
curl -X POST https://app.trueroas.com/api/v1/data \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pixelId": "your-store-id", "since": "2026-09-01", "until": "2026-09-30"}'
- Send a POST request to
https://app.trueroas.com/api/v1/data. - Add the header
Authorizationwith the valueBearer, a space and your key, and the headerContent-Typewith the valueapplication/json. - Put these fields in the JSON body:
| Field | Required | What to put in it |
|---|---|---|
pixelId | Yes | Your store's ID. Copy it from the example on the page. |
since | No | The first day, written as YYYY-MM-DD. |
until | No | The last day, written as YYYY-MM-DD. |
Without since and until, you get the period from 7 days ago up to today.
To pull another store, select it at the top of the left menu and the example on the page changes to that store's ID. See How do I switch between my stores?.
The address accepts requests from any website, so a spreadsheet script or your own tool can call it directly.
What you get back
Under Example Response, the page shows a shortened response from a real store.
Attribution is how TrueROAS decides which ad or channel gets the credit for a sale. In the response, the sales numbers are what TrueROAS gave each channel with your store's attribution settings, shown next to what each ad platform reports about itself.
| Part | What it holds |
|---|---|
dateRange | since and until, plus previousSince and previousUntil, the period of the same length just before. |
totals | All channels added together, such as spend, sales, newSales (sales to first-time customers), conversions, impressions and clicks. grossSales and totalOrders cover every order in the period with a value above zero, including orders TrueROAS could not tie to a channel. previous holds the earlier period and delta the change in percent. |
channels | One entry per channel: meta, google, tiktok, pinterest, bing (Microsoft Ads), snapchat, applovin, email, direct, googleOrganic (Google search without ads) and other. Each has spend, platformSales (what the ad platform reports), sales (what TrueROAS gave the channel), newSales, conversions and assists, with its own previous and delta. |
dailyStats | Sales and orders per channel for each day. previousDailyStats holds the same for the earlier period. |
explanation | A short description of each field. |
meta | Details about the request, such as orderCount, durationMs (how long the request took) and cacheHit (whether a stored answer was used). |
- When the store owner has the Incremental Attribution switch on, the
incrementalpart holds the adjusted numbers. When the switch is off, that part is empty (null). The other parts always keep the numbers without it. See What is Incremental Attribution and how does it work?. spendandplatformSalesare in the currency of each ad account, named in the channel'scurrency. If your ad accounts use different currencies, the totals add them up as they are.- Snapchat is listed, but its spend and platform numbers are always 0. AppLovin spend covers the last 90 days only, is in US dollars and has no platform sales.
- TrueROAS stores each answer and gives it again for the same request: for up to 15 minutes when the period includes today, up to 24 hours for a period that ended before today, and 2 minutes when one of your ad platforms could not be loaded.
When a request fails
The message comes back in the error field of the JSON answer.
| Code | Message | What to do |
|---|---|---|
| 401 | Missing or invalid Authorization header. Use: Bearer <api-key> | Add the Authorization header with Bearer and your key. |
| 401 | API key is empty | Put your key after Bearer. |
| 401 | Invalid or revoked API key | Copy the current key from API Access. |
| 400 | Missing required field: pixelId | Add your store's ID to the body. |
| 403 | You do not have access to this store | Use the ID of a store on your login. |
| 405 | Method not allowed. Use POST. | Send a POST request. |
| 500 | Internal server error | Try again later. |
Regenerate or revoke your key
- Regenerate makes a new key straight away. The old key stops working at once, and there is no question first. Put the new key everywhere you used the old one.
- Revoke switches the key off. You see API key revoked, and the Generate API Key button comes back.
A message such as Failed to generate API key or Failed to revoke API key means it did not work. Try again.
Good to know
- You have one API key per login, and it works for every store on your login. If a store that was shared with you answers
You do not have access to this store, select that store in TrueROAS once and try again. - Anyone who has your key can read your store data. If it leaks, click Regenerate.
- The API only reads data. It cannot change ads, budgets or settings.
- The response has totals per channel and per day, not per campaign or ad. To download campaign numbers as a file, see How do I export my campaign data to a CSV file?.
- The page says you can use the key with ChatGPT or Claude. To connect Claude or ChatGPT straight to TrueROAS, use the Claude, ChatGPT & more card instead, where this key does not work. See How do I connect Claude or ChatGPT to TrueROAS?.