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.
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 fields
Fields returned in the 200 response body. Nested objects are listed under their parent. A field marked optional may be absent from the body; one marked nullable is always present but its value may be null.
| Field | Type | Description |
|---|---|---|
segments | object[] | One segment per session_type value found in the date range. Events without a session_type metadata value are excluded from this comparison. |
session_type | string | Session type label being aggregated (e.g., "singleplayer", "multiplayer"). |
session_count | number (double) | Number of sessions with this session type in the date range. |
total_cost | string | Total cost across all sessions of this type (USD, decimal string). |
avg_cost_per_session | string | Average cost per session for this type (USD, decimal string). |
total_event_count | number (double) | Total usage events across all sessions of this type. |
cost_efficiency_ratio | number (double) nullable | Weighted average cost per session of the non-"singleplayer" segments divided by the "singleplayer" segment's average cost per session. Values below 1 mean those sessions cost less on average. Null when the range lacks a "singleplayer" segment, lacks any other segment, or the "singleplayer" average cost per session is zero. |
savings_percent | number (double) nullable | Per-session savings relative to the "singleplayer" baseline, computed as (1 - cost_efficiency_ratio) * 100. Null under the same conditions as cost_efficiency_ratio. |
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.