GamebeastDocs
Dashboard

Execute retention query

POST
/application/{applicationId}/analytics/v1/queries/retention/execute

Execute a retention query: of the users who performed the start event, how many performed the return event N days, weeks or months later. Cohorts are measured forward from the start event: time selects the cohorts (every day, week or month it touches), and returns are counted after it ends. retentionCriteria.returnOn counts a return in window N only (exact, the default) or in window N or any later one (on_or_after). options.display picks the result: a time series or single number at one offset (retentionGroup), or every cohort at every offset (retention_curve, retention_grid). Values that cannot be measured yet are null with state: "pending", never zero.

Authorization

AuthorizationBearer <token>

Secret server key (prefixed gb_sk_) for server-to-server calls. Send it as Authorization: Bearer <key>. Never ship a secret key in a game client.

In: header

Path Parameters

applicationId*number

Gamebeast project ID

Header Parameters

environment_id*number

Gamebeast environment ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

curl -X POST "https://example.com/application/0/analytics/v1/queries/retention/execute" \  -H "environment_id: 0" \  -H "Content-Type: application/json" \  -d '{    "time": {      "step": "second",      "relative": {        "step": "second",        "value": 0      }    },    "metrics": [      {        "id": "string",        "visible": true,        "data": {          "name": "string",          "type": "event"        }      },      {        "id": "string",        "visible": true,        "data": {          "name": "string",          "type": "event"        }      }    ],    "retentionCriteria": {      "measurement": "retention_rate",      "retentionWindow": "day"    },    "options": {      "display": "retention_curve"    }  }'
Empty