Attribution Data API

Compare session types

Returns a per-session-type cost comparison with a cost efficiency ratio. Call it with a GET request to /attribution-data/session-comparison, authenticated with a restricted API key and the "costs:read" scope.

GET https://api.bearlumen.com/v1/attribution-data/session-comparison

Returns a per-session-type cost comparison with a cost efficiency ratio. `cost_efficiency_ratio` is the weighted average cost per session of the non-"singleplayer" segments divided by the "singleplayer" segment's average cost per session, so values below 1 mean those sessions cost less on average. `savings_percent` is (1 - cost_efficiency_ratio) * 100. Both are null when the range lacks a "singleplayer" segment, lacks any other segment, or the "singleplayer" average cost per session is zero. Include `session_id` on your usage events to group them into sessions; optionally include `session_type` (any string label). Events without `session_id` are excluded, and events without `session_type` are excluded from this comparison entirely. Requests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.

Authentication and scopes

Authenticate with a restricted API key in the Authorization: Bearer <key> header. This endpoint requires the costs:read scope.

Parameters

Name	In	Type	Required	Description
`start_date`	query	`string`	Yes	Start of date range (ISO 8601, inclusive). If start_date is not before end_date the response is empty rather than an error.
`end_date`	query	`string`	Yes	End of date range (ISO 8601, exclusive).

Response example

Success response (200):

{
  "cost_efficiency_ratio": 1.328125,
  "savings_percent": -32.8125,
  "segments": [
    {
      "avg_cost_per_session": "8.5",
      "session_count": 2,
      "session_type": "multiplayer",
      "total_cost": "17",
      "total_event_count": 7
    },
    {
      "avg_cost_per_session": "6.4",
      "session_count": 2,
      "session_type": "singleplayer",
      "total_cost": "12.8",
      "total_event_count": 4
    }
  ]
}

Error codes

Errors return the standard error envelope with a code, message, and a correlationId you can quote to support.

Status	When it happens
`400`	Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.
`401`	Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.
`403`	API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.
`429`	Rate limit or plan quota exceeded. Slow down and retry after the current window resets.

Rate limits and retries

Rate limit or plan quota exceeded. Slow down and retry after the current window resets.