Analytics API

The Analytics API provides 5 campaign-level endpoints and 3 revenue endpoints for tracking impressions, spend, geographic distribution, affinity effectiveness, and budget pacing. All endpoints require Bearer token authentication and return JSON.

Campaign Analytics

All campaign analytics endpoints are scoped to a single campaign by ID. The authenticated user must own the campaign or have admin access.

1. Daily Time Series

GET /api/ads/campaigns/{id}/analytics/daily

Returns a time series of impressions and spend aggregated by day. Use this to chart campaign performance over time and identify trends.

Query Parameters

Parameter	Type	Default	Description
`days`	integer	30	Number of days to look back. Range: 1-365.

Example Request

curl -s "https://api.scrya.com/api/ads/campaigns/camp_abc123/analytics/daily?days=7" \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

[
  {
    "date": "2026-02-22",
    "impressions": 342,
    "spent_cents": 6840
  },
  {
    "date": "2026-02-23",
    "impressions": 417,
    "spent_cents": 8340
  },
  {
    "date": "2026-02-24",
    "impressions": 289,
    "spent_cents": 5780
  },
  {
    "date": "2026-02-25",
    "impressions": 501,
    "spent_cents": 10020
  },
  {
    "date": "2026-02-26",
    "impressions": 378,
    "spent_cents": 7560
  },
  {
    "date": "2026-02-27",
    "impressions": 456,
    "spent_cents": 9120
  },
  {
    "date": "2026-02-28",
    "impressions": 312,
    "spent_cents": 6240
  }
]

Each entry represents one day. spent_cents is the total CPM-based spend for that day (impressions * cpm_bid_cents / 1000). Days with zero impressions are included in the range with impressions: 0 and spent_cents: 0.

2. Per-Creative Breakdown

GET /api/ads/campaigns/{id}/analytics/creatives

Returns performance metrics broken down by creative. Use this to identify which creatives are performing best and which may need adjustment.

Example Request

curl -s "https://api.scrya.com/api/ads/campaigns/camp_abc123/analytics/creatives" \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

[
  {
    "creative_id": "crt_def456",
    "brand_name": "Acme Corp",
    "creative_type": "narrative_hook",
    "impressions": 1847,
    "spent_cents": 36940,
    "last_shown": "2026-02-28T14:32:00Z"
  },
  {
    "creative_id": "crt_ghi789",
    "brand_name": "Acme Corp",
    "creative_type": "product_mention",
    "impressions": 923,
    "spent_cents": 18460,
    "last_shown": "2026-02-28T11:15:00Z"
  },
  {
    "creative_id": "crt_jkl012",
    "brand_name": "Acme Corp",
    "creative_type": "location_brand",
    "impressions": 412,
    "spent_cents": 8240,
    "last_shown": "2026-02-27T22:45:00Z"
  }
]

Results are sorted by impressions descending. last_shown is an ISO 8601 timestamp of the most recent impression for that creative.

3. Geographic Breakdown

GET /api/ads/campaigns/{id}/analytics/geo

Returns impressions and spend aggregated by country. Use this to understand the geographic distribution of your campaign reach and optimize geo targeting.

Example Request

curl -s "https://api.scrya.com/api/ads/campaigns/camp_abc123/analytics/geo" \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

[
  {
    "country_code": "US",
    "impressions": 1523,
    "spent_cents": 30460
  },
  {
    "country_code": "GB",
    "impressions": 487,
    "spent_cents": 9740
  },
  {
    "country_code": "DE",
    "impressions": 312,
    "spent_cents": 6240
  },
  {
    "country_code": "CA",
    "impressions": 198,
    "spent_cents": 3960
  },
  {
    "country_code": "AU",
    "impressions": 162,
    "spent_cents": 3240
  }
]

Country codes follow ISO 3166-1 alpha-2. Results are sorted by impressions descending. Countries with zero impressions are omitted.

4. Affinity Effectiveness

GET /api/ads/campaigns/{id}/analytics/affinities

Returns how often each of your campaign's affinities matched a scene during impression recording. Use this to see which affinities are driving the most matches and refine your targeting strategy.

Example Request

curl -s "https://api.scrya.com/api/ads/campaigns/camp_abc123/analytics/affinities" \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

[
  {
    "affinity_type": "lighting",
    "affinity_value": "warm",
    "weight": 2.0,
    "matched_impressions": 1847
  },
  {
    "affinity_type": "effects",
    "affinity_value": "cinematic",
    "weight": 1.5,
    "matched_impressions": 1623
  },
  {
    "affinity_type": "category",
    "affinity_value": "simulation",
    "weight": 1.0,
    "matched_impressions": 1204
  },
  {
    "affinity_type": "mood",
    "affinity_value": "triumphant",
    "weight": 1.5,
    "matched_impressions": 487
  },
  {
    "affinity_type": "action",
    "affinity_value": "celebration",
    "weight": 1.0,
    "matched_impressions": 312
  },
  {
    "affinity_type": "location",
    "affinity_value": "rooftop terrace",
    "weight": 1.0,
    "matched_impressions": 89
  }
]

matched_impressions is the count of impressions where this specific affinity contributed to the match score. Note that lighting and effects affinities always apply (they are visual overrides), so their matched count tends to equal total impressions. Context-dependent affinities like action and mood will have lower match rates.

5. Budget Pacing

GET /api/ads/campaigns/{id}/analytics/pacing

Returns budget pacing information: whether the campaign is spending too fast, too slow, or on track relative to its flight dates and total budget.

Example Request

curl -s "https://api.scrya.com/api/ads/campaigns/camp_abc123/analytics/pacing" \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

{
  "daily_cap_cents": 15000,
  "avg_daily_spend_cents": 12740,
  "days_elapsed": 14,
  "days_remaining": 16,
  "projected_total_spend_cents": 382200,
  "on_track": true
}

Field	Type	Description
`daily_cap_cents`	integer	Budget divided by total flight days. The ideal daily spend to evenly distribute budget.
`avg_daily_spend_cents`	integer	Actual average daily spend so far (total spent / days elapsed).
`days_elapsed`	integer	Number of days since campaign start_date.
`days_remaining`	integer	Number of days until campaign end_date.
`projected_total_spend_cents`	integer	avg_daily_spend * (days_elapsed + days_remaining). What the campaign will spend if the current pace continues.
`on_track`	boolean	`true` if projected spend is within 20% of total budget; `false` if overpacing or underpacing.

Use the on_track flag and the ratio of avg_daily_spend_cents to daily_cap_cents to decide whether to adjust your CPM bid. If avg_daily_spend > daily_cap, the campaign is overpacing and may exhaust budget early. If significantly under, the campaign may underspend.

Revenue Endpoints

In addition to campaign analytics, there are three revenue endpoints for tracking earnings and spend across accounts and games.

Advertiser Total Spend

GET /api/ads/revenue

Returns the total amount the authenticated advertiser has spent across all campaigns.

Example Request

curl -s "https://api.scrya.com/api/ads/revenue" \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

{
  "total_spent_cents": 458300,
  "active_campaigns": 3,
  "total_impressions": 22915
}

Creator Total Earnings

GET /api/ads/creator-revenue

Returns the total amount the authenticated game developer has earned across all their games. Earnings are calculated as the advertiser spend multiplied by the creator's revenue share percentage (typically 70%).

Example Request

curl -s "https://api.scrya.com/api/ads/creator-revenue" \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

{
  "total_earned_cents": 320810,
  "revenue_share_pct": 70,
  "total_impressions": 22915,
  "games_count": 2
}

Per-Game Earnings

GET /api/ads/creator-revenue/{game_id}

Returns earnings for a specific game. Use this to compare monetization performance across your game portfolio.

Example Request

curl -s "https://api.scrya.com/api/ads/creator-revenue/my_game_id" \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

{
  "game_id": "my_game_id",
  "total_earned_cents": 187250,
  "revenue_share_pct": 70,
  "total_impressions": 13375,
  "active_campaigns_serving": 5,
  "top_campaign": {
    "campaign_id": "camp_abc123",
    "brand_name": "Acme Corp",
    "impressions": 4231,
    "earned_cents": 59234
  }
}

Authentication

All analytics endpoints require a valid API key passed as a Bearer token:

Authorization: Bearer sk_live_your_api_key_here

Campaign analytics endpoints verify that the authenticated user owns the campaign. Revenue endpoints return data scoped to the authenticated user's account.

Rate Limits

Analytics endpoints are rate-limited to 60 requests per minute per API key. The daily and pacing endpoints cache results for 5 minutes, so frequent polling will return cached data without counting against your rate limit.

Ad Matching Pipeline -- understand how impressions are generated
Affinity Targeting -- optimize your affinities based on analytics data
Pricing Model -- CPM pricing and budget planning
Revenue Model -- how creator earnings are calculated
Quickstart -- get your first impression flowing

Analytics API

Campaign Analytics

1. Daily Time Series

Query Parameters

Example Request

Example Response

2. Per-Creative Breakdown

Example Request

Example Response

3. Geographic Breakdown

Example Request

Example Response

4. Affinity Effectiveness

Example Request

Example Response

5. Budget Pacing

Example Request

Example Response

Revenue Endpoints

Advertiser Total Spend

Example Request

Example Response

Creator Total Earnings

Example Request

Example Response

Per-Game Earnings

Example Request

Example Response

Authentication

Rate Limits

Related