X-API-Key authenticated reporting API that returns aggregated gameplay metrics - DAU/MAU, retention (retention_retro), ARPU/ARPPU/ARPDAU, session length, revenue and ad revenue - as JSON, queried by POSTing an interval, granularity, and a group/split/timeseries query object per metric.
openapi: 3.0.3
info:
title: GameAnalytics REST APIs
description: >-
Representative OpenAPI description of the public GameAnalytics REST surfaces:
the Collection (Collector) API for HMAC-signed event ingestion, the Metrics
API for aggregated reporting, and the Organization API for programmatic
administration of games, studios, users, and permissions. Endpoints and
authentication reflect the public GameAnalytics documentation; consult the
docs for the full request/response payloads, which are large and evolving.
termsOfService: https://gameanalytics.com/terms/
contact:
name: GameAnalytics Support
url: https://gameanalytics.com/contact/
version: '1.0'
servers:
- url: https://api.gameanalytics.com
description: Collection API - production
- url: https://sandbox-api.gameanalytics.com
description: Collection API - sandbox
- url: https://metrics.gameanalytics.com
description: Metrics API
- url: https://organization.gameanalytics.com
description: Organization API
tags:
- name: Collection
description: HMAC-signed event ingestion (Collector API).
- name: Metrics
description: Aggregated gameplay metrics and reporting.
- name: Organization
description: Programmatic administration of games, studios, users, and permissions.
paths:
/v2/{game_key}/init:
post:
operationId: collectionInit
tags:
- Collection
summary: Initialize an SDK/collection session.
description: >-
Returns a server timestamp and an `enabled` flag before events are sent.
The request body must be signed with an HMAC-SHA256 digest of the raw
(optionally gzipped) body using the game secret key, base64-encoded, and
supplied in the `Authorization` header. HTTPS is required.
security:
- hmacAuth: []
parameters:
- $ref: '#/components/parameters/GameKey'
- $ref: '#/components/parameters/ContentEncoding'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitRequest'
responses:
'200':
description: Initialization succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/InitResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/{game_key}/events:
post:
operationId: collectionEvents
tags:
- Collection
summary: Submit a batch of game events.
description: >-
Accepts a JSON array of event objects (categories include `user`,
`session_end`, `business`, `resource`, `progression`, `design`, `error`,
and `ads`). The gzipped body must be signed with an HMAC-SHA256 digest
using the game secret key (base64) in the `Authorization` header. POST
size limit is 1 MB; gzip is strongly recommended.
security:
- hmacAuth: []
parameters:
- $ref: '#/components/parameters/GameKey'
- $ref: '#/components/parameters/ContentEncoding'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Event'
responses:
'200':
description: Events accepted.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'413':
description: Payload exceeds the 1 MB POST size limit.
/metrics/v1/metrics/{metric}:
post:
operationId: queryMetric
tags:
- Metrics
summary: Query an aggregated gameplay metric.
description: >-
Returns aggregated metric data (for example `dau`, `mau`,
`retention_retro`, `arpu`, `arppu`, `session_length`, `revenue`,
`ad_revenue`) as JSON. Authenticated with the `X-API-Key` header. The
body specifies an ISO-8601 `interval`, a `granularity`, an optional
`game` id, and a `query` object of type `group`, `split`, or
`timeseries`.
servers:
- url: https://metrics.gameanalytics.com
security:
- apiKeyHeader: []
parameters:
- name: metric
in: path
required: true
description: The metric to query (e.g. dau, mau, retention_retro, arpu, arppu, session_length).
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsQuery'
responses:
'200':
description: Metric result.
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsResult'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v1/games:
get:
operationId: listGames
tags:
- Organization
summary: List all games in the organization.
servers:
- url: https://organization.gameanalytics.com
security:
- apiKeyHeader: []
responses:
'200':
description: A list of games.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Game'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createGame
tags:
- Organization
summary: Create a game.
servers:
- url: https://organization.gameanalytics.com
security:
- apiKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Game'
responses:
'200':
description: The created game.
content:
application/json:
schema:
$ref: '#/components/schemas/Game'
/api/v1/games/{game_id}:
get:
operationId: getGame
tags:
- Organization
summary: Retrieve a single game.
servers:
- url: https://organization.gameanalytics.com
security:
- apiKeyHeader: []
parameters:
- name: game_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: A game object.
content:
application/json:
schema:
$ref: '#/components/schemas/Game'
/api/v1/studios:
get:
operationId: listStudios
tags:
- Organization
summary: List all studios in the organization.
servers:
- url: https://organization.gameanalytics.com
security:
- apiKeyHeader: []
responses:
'200':
description: A list of studios.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Studio'
post:
operationId: createStudio
tags:
- Organization
summary: Create a studio.
servers:
- url: https://organization.gameanalytics.com
security:
- apiKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Studio'
responses:
'200':
description: The created studio.
content:
application/json:
schema:
$ref: '#/components/schemas/Studio'
/api/v1/studios/{studio_id}:
get:
operationId: getStudio
tags:
- Organization
summary: Retrieve a single studio.
servers:
- url: https://organization.gameanalytics.com
security:
- apiKeyHeader: []
parameters:
- name: studio_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: A studio object.
content:
application/json:
schema:
$ref: '#/components/schemas/Studio'
/api/v1/users:
get:
operationId: listUsers
tags:
- Organization
summary: List all users in the organization.
servers:
- url: https://organization.gameanalytics.com
security:
- apiKeyHeader: []
responses:
'200':
description: A list of users.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
/api/v1/users/invite:
post:
operationId: inviteUser
tags:
- Organization
summary: Invite a user to the organization.
servers:
- url: https://organization.gameanalytics.com
security:
- apiKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserInvite'
responses:
'200':
description: Invitation sent.
/api/v1/users/{user_id}/replace_acl:
post:
operationId: replaceUserAcl
tags:
- Organization
summary: Replace a user's access permissions (ACL).
servers:
- url: https://organization.gameanalytics.com
security:
- apiKeyHeader: []
parameters:
- name: user_id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Acl'
responses:
'200':
description: Permissions updated.
components:
securitySchemes:
hmacAuth:
type: apiKey
in: header
name: Authorization
description: >-
Base64-encoded HMAC-SHA256 digest of the raw (optionally gzipped)
request body, keyed with the game's secret key. Used by the Collection
API.
apiKeyHeader:
type: apiKey
in: header
name: X-API-Key
description: >-
API key generated in the GameAnalytics dashboard. The Metrics API uses
the `X-API-Key` header; the Organization API uses an equivalent API-key
header.
parameters:
GameKey:
name: game_key
in: path
required: true
description: The public game key identifying the game in GameAnalytics.
schema:
type: string
ContentEncoding:
name: Content-Encoding
in: header
required: false
description: Set to `gzip` when the body is gzip-compressed (strongly recommended).
schema:
type: string
enum:
- gzip
responses:
BadRequest:
description: The request was malformed or failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid authentication (bad HMAC signature or API key).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
code:
type: string
message:
type: string
InitRequest:
type: object
properties:
platform:
type: string
example: ios
os_version:
type: string
example: ios 17.0
sdk_version:
type: string
example: rest api v2
InitResponse:
type: object
properties:
enabled:
type: boolean
description: Whether event collection is enabled for this game.
server_ts:
type: integer
format: int64
description: Server-side Unix timestamp used to correct client clocks.
Event:
type: object
description: >-
A single GameAnalytics event. The `category` field determines which
additional fields are required. See the Collection API docs for the full
set of fields per category.
required:
- category
properties:
category:
type: string
enum:
- user
- session_end
- business
- resource
- progression
- design
- error
- ads
description: The event category.
v:
type: integer
example: 2
user_id:
type: string
session_id:
type: string
session_num:
type: integer
client_ts:
type: integer
format: int64
sdk_version:
type: string
os_version:
type: string
manufacturer:
type: string
device:
type: string
platform:
type: string
build:
type: string
event_id:
type: string
description: For design/progression/resource events, the hierarchical event identifier.
amount:
type: number
description: For business/resource events, the transaction or resource amount.
currency:
type: string
description: For business events, the ISO 4217 currency code.
value:
type: number
description: For design events, an optional numeric value.
MetricsQuery:
type: object
required:
- interval
- granularity
- query
properties:
game:
type: integer
description: The game id to query (optional for some query types).
interval:
type: string
description: ISO-8601 interval, e.g. "2026-06-01/P1W".
example: 2026-06-01/P1W
granularity:
type: string
enum:
- day
- week
- all
days_since_install:
type: array
items:
type: integer
description: Optional cohort array (0-90) for retention-style metrics.
filter:
type: object
additionalProperties: true
query:
type: object
description: The query specification.
properties:
type:
type: string
enum:
- group
- split
- timeseries
dimensions:
type: array
items:
type: string
limit:
type: integer
MetricsResult:
type: object
properties:
interval:
type: string
granularity:
type: string
results:
type: array
items:
type: object
additionalProperties: true
Game:
type: object
properties:
id:
type: integer
name:
type: string
studio_id:
type: integer
platform:
type: string
game_key:
type: string
secret_key:
type: string
Studio:
type: object
properties:
id:
type: integer
name:
type: string
User:
type: object
properties:
id:
type: integer
email:
type: string
format: email
name:
type: string
UserInvite:
type: object
required:
- email
properties:
email:
type: string
format: email
acl:
$ref: '#/components/schemas/Acl'
Acl:
type: object
description: Access control list mapping games/studios to permission roles.
properties:
studios:
type: array
items:
type: object
properties:
studio_id:
type: integer
role:
type: string
enum:
- admin
- member
- viewer
games:
type: array
items:
type: object
properties:
game_id:
type: integer
role:
type: string
enum:
- admin
- member
- viewer