All requests require an API key passed in the x-api-key header. Create keys in Settings → API Keys.
Base URL
https://api.roas.to/external/v1/facebookExample Request
curl -H "x-api-key: roas_your_key_here" \ "https://api.roas.to/external/v1/facebook/campaigns?start_date=2026-03-29&end_date=2026-04-05"
Read-only
Only GET requests. No writes.
Local timestamps
Dates returned in your workspace's reporting timezone (see the X-Timezone response header).
Budget units
Budget fields ending in Minor use account-currency minor units.
Every performance endpoint returns both Facebook-reported metrics and your true tracked metrics side by side.
| Field | Source | Description |
|---|---|---|
fbImpressions | Facebook | Total impressions (Facebook-reported) |
fbClicks | Facebook | Total clicks (all types) |
fbLinkClicks | Facebook | Link clicks only (outbound) |
fbSpend | Facebook | Total spend in account currency |
fbReach | Facebook | Unique users reached |
fbCtr | Facebook | Click-through rate (%) |
fbCpc | Facebook | Cost per click |
fbCpm | Facebook | Cost per 1,000 impressions |
fbPurchases | Facebook | Facebook-reported purchases (pixel) |
fbPurchaseValue | Facebook | Facebook-reported purchase value |
ourConversions | ROAS.to | Conversions tracked by ROAS.to |
ourRevenue | ROAS.to | Revenue tracked by ROAS.to |
trueConversions | ROAS.to | Conversions per your conversion-source setting (tracker or FB pixel) |
trueRevenue | ROAS.to | Revenue per your conversion-source setting (tracker or FB pixel) |
trueRoas | ROAS.to | trueRevenue / fbSpend — null when spend or revenue is zero |
trueCpa | ROAS.to | fbSpend / trueConversions — null when there are no conversions |
profitLoss | ROAS.to | trueRevenue - fbSpend (daily endpoint only) |
60 requests / minute
Per API key. Check response headers for remaining quota.
1,000 max per page
Use limit + offset for pagination. Default: 100. Lists are ordered newest-first by creation time. Responses return the page's row count (no grand total) — page until a short page comes back.
Rate Limit Headers
| Header | Description |
|---|---|
X-RateLimit-Limit | Max requests per window (60) |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
X-Timezone | Timezone of response timestamps (your workspace's reporting timezone, e.g. America/New_York) |
Error Codes
| Status | Meaning |
|---|---|
400 | Invalid request (e.g. date range wider than 548 days) |
401 | Missing or invalid API key |
404 | Resource not found (or belongs to another workspace) |
405 | Method not allowed (only GET is supported) |
429 | Rate limit exceeded. Wait and retry. |
500 | Internal server error. Contact support@roas.to. |