Logo

Documentación de la API

Arrow left Volver a la app

Documentación de la API

Game Stats AI API

Overview

This API is used to import data from your game. It's recommended to call the API from a backend server supporting your game but you can also call it from clients of the game.

In order to use the API you'll need to know your API token and your account ID. API tokens are scoped to an account and can be created on the API tokens page in your account settings at https://gamestats.ai/api_tokens. Your account ID is shown on that same API tokens page.

Send the key on every request in the Authorization header using the Bearer scheme: Authorization: Bearer <token>.

MCP server

We also host a Model Context Protocol (MCP) server so AI assistants can read your analytics. Point an MCP client at /api/v1/mcp. Clients that support MCP OAuth (such as Claude and ChatGPT connectors) sign in and approve access without a token; other clients can send the same Authorization: Bearer <token> header with a server token. It exposes read-only tools: the read endpoints in this spec (reports, accounts, the authenticated user, and ping), plus the in-app assistant's data tools (account overview, dashboard KPIs, report catalog, versions, event names, attribute types, player, character, match, and archetype lookups, and live counts, breakdowns, histograms, and time series). Call tools/list for the full, self-describing tool catalog.

URL base: https://gamestats.ai

Getting Started

Verify connectivity and authentication before sending game data.

It's recommended to successfully call the ping endpoint and monitor https://gamestats.ai/pings to confirm that your requests are reaching the API before moving on to the rest of the endpoints.

List your accounts

Respuestas

  • 200 accounts listed
  • 401 unauthorized
get /api/v1/accounts
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts"

Ejemplo de respuesta

[
  {
    "id": 12,
    "name": "My Game"
  },
  {
    "id": 34,
    "name": "My Other Game"
  }
]

Show the authenticated user

Respuestas

  • 200 authenticated user returned
get /api/v1/me
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/me"

Pings the API

Respuestas

  • 201 ping received
post /api/v1/pings
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/pings"

List the versions for a game

List the released versions of your game, most recent first. Use a version id to filter matches and reports by the version they belong to.

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 versions listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/versions
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/versions"

Ejemplo de respuesta

[
  {
    "id": 21,
    "name": "1.4",
    "created_at": "2026-07-20T18:00:00.000Z"
  },
  {
    "id": 12,
    "name": "1.3",
    "created_at": "2026-06-01T18:00:00.000Z"
  }
]

Matches

Track what happens during a match between a number of players.

The characters endpoint only needs to be called once for each character when a new version of your game is released.

The character images endpoint is used to upload an image of a character to be displayed alongside character names in reports. This is optional and only needs to be done once per character.

The matches endpoint should be called once at the end of each match.

List attribute reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 attribute reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/attribute_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/attribute_reports"

Ejemplo de respuesta

[
  {
    "id": 12,
    "label": "Win Rate by Stage",
    "description": "Win rate broken down by match attribute."
  },
  {
    "id": 15,
    "label": "Rounds by Stage",
    "description": "Number of rounds played on each stage."
  }
]

Show an attribute report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
page query integer No Page of report rows to return (1-based, defaults to 1). The response `pagination` object reports the current `page`, total row `count`, and total number of `pages`; request pages 1..`pages` to read the full report.
version_id query array No Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array No Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array No Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array No Minimum and maximum bounds for the report threshold filter, as [min, max].

Respuestas

  • 200 attribute report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/attribute_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/attribute_reports/{id}?page=2"

Ejemplo de respuesta

{
  "id": 12,
  "label": "Win Rate by Stage",
  "description": "Win rate broken down by match attribute.",
  "metrics": [
    {
      "label": "Wins",
      "format": "unformatted"
    },
    {
      "label": "Win Rate",
      "format": "percentage"
    }
  ],
  "filters": [
    {
      "name": "version_id",
      "type": "category",
      "label": "Version",
      "values": [
        {
          "value": "1",
          "label": "1.0"
        }
      ]
    },
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    }
  ],
  "rows": [
    {
      "subject": "Volcanic Rim",
      "values": [
        {
          "metric": "Wins",
          "value": 512
        },
        {
          "metric": "Win Rate",
          "value": 0.54
        }
      ]
    },
    {
      "subject": "Suzaku Castle",
      "values": [
        {
          "metric": "Wins",
          "value": 431
        },
        {
          "metric": "Win Rate",
          "value": 0.48
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "count": 2,
    "pages": 1
  }
}

List character attribute reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 character attribute reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/character_attribute_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/character_attribute_reports"

Ejemplo de respuesta

[
  {
    "id": 12,
    "label": "Win Rate by Element and Rarity",
    "description": "Win rate grouped by character attributes."
  },
  {
    "id": 19,
    "label": "Pick Rate by Element",
    "description": "Pick rate grouped by character element."
  }
]

Show a character attribute report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
page query integer No Page of report rows to return (1-based, defaults to 1). The response `pagination` object reports the current `page`, total row `count`, and total number of `pages`; request pages 1..`pages` to read the full report.
version_id query array No Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array No Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array No Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array No Minimum and maximum bounds for the report threshold filter, as [min, max].

Respuestas

  • 200 character attribute report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/character_attribute_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/character_attribute_reports/{id}?page=2"

Ejemplo de respuesta

{
  "id": 12,
  "label": "Win Rate by Element and Rarity",
  "description": "Win rate grouped by character attributes.",
  "metrics": [
    {
      "label": "Win Rate",
      "format": "percentage"
    }
  ],
  "filters": [
    {
      "name": "version_id",
      "type": "category",
      "label": "Version",
      "values": [
        {
          "value": "1",
          "label": "1.0"
        }
      ]
    },
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    }
  ],
  "rows": [
    {
      "subject": "Fire / Legendary",
      "attributes": [
        {
          "name": "element",
          "value": "Fire"
        },
        {
          "name": "rarity",
          "value": "Legendary"
        }
      ],
      "values": [
        {
          "metric": "Win Rate",
          "value": 0.63
        }
      ]
    },
    {
      "subject": "Water / Rare",
      "attributes": [
        {
          "name": "element",
          "value": "Water"
        },
        {
          "name": "rarity",
          "value": "Rare"
        }
      ],
      "values": [
        {
          "metric": "Win Rate",
          "value": 0.49
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "count": 2,
    "pages": 1
  }
}

Create a Character Image

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
character_external_id formData string Sí The external ID you used in the Characters API
image formData file Sí The image of the character

Respuestas

  • 201 character image created
post /api/v1/accounts/{account_id}/character_images
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -F "character_external_id=string" \
  -F "image=@/path/to/image.png" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/character_images"

List character reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 character reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/character_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/character_reports"

Ejemplo de respuesta

[
  {
    "id": 12,
    "label": "Damage by Character",
    "description": "Average damage dealt by each character."
  },
  {
    "id": 18,
    "label": "Win Rate by Character",
    "description": "Win rate for each character."
  }
]

Show a character report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
page query integer No Page of report rows to return (1-based, defaults to 1). The response `pagination` object reports the current `page`, total row `count`, and total number of `pages`; request pages 1..`pages` to read the full report.
version_id query array No Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array No Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array No Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array No Minimum and maximum bounds for the report threshold filter, as [min, max].

Respuestas

  • 200 character report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/character_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/character_reports/{id}?page=2"

Ejemplo de respuesta

{
  "id": 12,
  "label": "Damage by Character",
  "description": "Average damage dealt by each character.",
  "metrics": [
    {
      "label": "Avg Damage",
      "format": "unformatted"
    },
    {
      "label": "Win Rate",
      "format": "percentage"
    }
  ],
  "filters": [
    {
      "name": "version_id",
      "type": "category",
      "label": "Version",
      "values": [
        {
          "value": "1",
          "label": "1.0"
        }
      ]
    },
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    }
  ],
  "rows": [
    {
      "subject": "Ryu",
      "values": [
        {
          "metric": "Avg Damage",
          "value": 1423.5
        },
        {
          "metric": "Win Rate",
          "value": 0.61
        }
      ]
    },
    {
      "subject": "Ken",
      "values": [
        {
          "metric": "Avg Damage",
          "value": 1387.2
        },
        {
          "metric": "Win Rate",
          "value": 0.57
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "count": 2,
    "pages": 1
  }
}

Create a Character for a Version

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Cuerpo de la solicitud (JSON)

Campo Tipo Obligatorio Descripción
external_id string Sí The external ID uniquely identifies a character. The same ID should be used across versions. If multiple requests are sent for the same external ID and version name, the existing records will be updated.
name string Sí The name of the character. This does not currently vary from version to version.
description string No This is a description of the character. It can be either plain text or Markdown. See https://www.markdownguide.org/cheat-sheet/ for an understanding of Markdown.
version_name string Sí The attributes in this request correspond to this version name. Character attributes can vary from version to version.
character_attributes object No Key-value pairs. These are displayed in reports and can be configured as filters.

Respuestas

  • 201 character for version queued for creation
  • 422 invalid request
post /api/v1/accounts/{account_id}/characters
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "your_character_id",
  "name": "A character",
  "description": "This is a **bolded** description. This is an *italicized* description.",
  "version_name": "1.0",
  "character_attributes": {
    "Type": "Fire",
    "Rarity": "Common"
  }
}' \
  "https://gamestats.ai/api/v1/accounts/{account_id}/characters"

Creates a Match

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Cuerpo de la solicitud (JSON)

Campo Tipo Obligatorio Descripción
external_id string No The external ID uniquely identifies a match. If multiple requests are sent for the same external ID, the existing records will be updated.
version_name string Sí The match in this request corresponds to this version name.
match_at string No The match in this request corresponds to this version name.
match_attributes object No
match_players object[] No

Respuestas

  • 201 match queued for creation
  • 402 monthly tracked record limit reached
  • 422 invalid request
post /api/v1/accounts/{account_id}/matches
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "your_match_id",
  "version_name": "1.0",
  "match_at": "2022-08-09T23:26:01UTC",
  "match_attributes": {
    "stage": "A stage"
  },
  "match_players": [
    {
      "username": "a_player_123",
      "match_attributes": {
        "elo": 1600
      },
      "match_events": [
        {
          "character_external_id": "your_character_id",
          "event_type_name": "chosen_fighter",
          "match_attributes": {
            "level": 42
          }
        }
      ]
    }
  ]
}' \
  "https://gamestats.ai/api/v1/accounts/{account_id}/matches"

List player reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 player reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/player_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/player_reports"

Ejemplo de respuesta

[
  {
    "id": 12,
    "label": "Matches Played by Player",
    "description": "Matches played by each player."
  },
  {
    "id": 21,
    "label": "Win Rate by Player",
    "description": "Win rate for each player."
  }
]

Show a player report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
page query integer No Page of report rows to return (1-based, defaults to 1). The response `pagination` object reports the current `page`, total row `count`, and total number of `pages`; request pages 1..`pages` to read the full report.
version_id query array No Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array No Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array No Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array No Minimum and maximum bounds for the report threshold filter, as [min, max].

Respuestas

  • 200 player report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/player_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/player_reports/{id}?page=2"

Ejemplo de respuesta

{
  "id": 12,
  "label": "Matches Played by Player",
  "description": "Matches played by each player.",
  "metrics": [
    {
      "label": "Matches",
      "format": "unformatted"
    },
    {
      "label": "Win Rate",
      "format": "percentage"
    }
  ],
  "filters": [
    {
      "name": "version_id",
      "type": "category",
      "label": "Version",
      "values": [
        {
          "value": "1",
          "label": "1.0"
        }
      ]
    },
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    }
  ],
  "rows": [
    {
      "subject": "shoto_main",
      "values": [
        {
          "metric": "Matches",
          "value": 214
        },
        {
          "metric": "Win Rate",
          "value": 0.58
        }
      ]
    },
    {
      "subject": "grappler99",
      "values": [
        {
          "metric": "Matches",
          "value": 188
        },
        {
          "metric": "Win Rate",
          "value": 0.44
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "count": 2,
    "pages": 1
  }
}

Progressions

Track level progress, player level, season progression and more over time.

The progression events endpoint should be called at the completion of a milestone (i.e. starting a level, finishing a level, collecting 100 coins, etc.).

Creates a Progression Event

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Cuerpo de la solicitud (JSON)

Campo Tipo Obligatorio Descripción
version_name string Sí The progression event in this request corresponds to this version name.
player_username string Sí The username for the player.
progression_name string Sí
progression_type_name string Sí
progression_milestone_name string Sí If not provided, the milestone name will be the same as the milestone type name.
progression_milestone_type_name string Sí
is_new_instance boolean No If provided, the progression event in this request is considered the start of a new instances occurring at this time. There's no need to provide started_at if this is set.
started_at string No If provided, the progression event in this request is considered the start of a new instances occurring at this time.
time_elapsed integer No This is the amount of "time" that has passed since the start of the instance. If this is the first event in the instance, it will likely be 0. Any unit of measurement can be used (ticks, seconds, minutes, etc) but you must be consistent across events.
occurred_at string Sí This represents the time the event occurs.

Respuestas

  • 201 progression event queued for creation
  • 402 monthly tracked record limit reached
  • 422 invalid request
post /api/v1/accounts/{account_id}/progression_events
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "version_name": "1.0",
  "player_username": "a_player_123",
  "progression_name": "string",
  "progression_type_name": "string",
  "progression_milestone_name": "string",
  "progression_milestone_type_name": "string",
  "is_new_instance": true,
  "started_at": "2022-08-09T23:26:01UTC",
  "time_elapsed": 0,
  "occurred_at": "2022-08-09T23:26:01UTC"
}' \
  "https://gamestats.ai/api/v1/accounts/{account_id}/progression_events"

List progression reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 progression reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/progression_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/progression_reports"

Ejemplo de respuesta

[
  {
    "id": 12,
    "label": "Level Progression",
    "description": "Completion rates and timing across levels."
  },
  {
    "id": 25,
    "label": "Season Progression",
    "description": "Progress through the current season."
  }
]

Show a progression report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
page query integer No Page of report rows to return (1-based, defaults to 1). The response `pagination` object reports the current `page`, total row `count`, and total number of `pages`; request pages 1..`pages` to read the full report.
version_id query array No Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array No Only include data from the last N days. Allowed values: 1, 7, 30.

Respuestas

  • 200 progression report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/progression_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/progression_reports/{id}?page=2"

Ejemplo de respuesta

{
  "id": 12,
  "label": "Level Progression",
  "description": "Completion rates and timing across levels.",
  "metrics": [
    {
      "label": "Completion Rate",
      "format": "percentage"
    },
    {
      "label": "Average Time Elapsed",
      "format": "unformatted"
    },
    {
      "label": "# of Instances",
      "format": "unformatted"
    }
  ],
  "filters": [
    {
      "name": "version_id",
      "type": "category",
      "label": "Version",
      "values": [
        {
          "value": "1",
          "label": "1.0"
        }
      ]
    },
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    }
  ],
  "rows": [
    {
      "subject": "Level 1",
      "values": [
        {
          "metric": "Completion Rate",
          "value": 0.92
        },
        {
          "metric": "Average Time Elapsed",
          "value": 142.5
        },
        {
          "metric": "# of Instances",
          "value": 5000
        }
      ]
    },
    {
      "subject": "Level 2",
      "values": [
        {
          "metric": "Completion Rate",
          "value": 0.78
        },
        {
          "metric": "Average Time Elapsed",
          "value": 210.3
        },
        {
          "metric": "# of Instances",
          "value": 4200
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "count": 2,
    "pages": 1
  }
}

Achievements

Define achievements and track unlock rates across players.

The achievement events endpoint should be called when a player unlocks an achievement. Achievements are created automatically the first time they are sent, and sending the same achievement for the same player again has no effect. You can also add an achievement directly (before any player unlocks it) so it counts toward your completion rates.

Creates an Achievement Event

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Cuerpo de la solicitud (JSON)

Campo Tipo Obligatorio Descripción
version_name string Sí The achievement unlock in this request corresponds to this version name.
player_username string Sí The username for the player.
achievement_name string Sí The name of the achievement the player unlocked. Achievements are created automatically the first time they are sent.
occurred_at string Sí This represents the time the player unlocked the achievement. Sending the same achievement for the same player again has no effect.

Respuestas

  • 201 achievement event queued for creation
  • 402 monthly tracked record limit reached
  • 422 invalid request
post /api/v1/accounts/{account_id}/achievement_events
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "version_name": "1.0",
  "player_username": "a_player_123",
  "achievement_name": "First Blood",
  "occurred_at": "2022-08-09T23:26:01UTC"
}' \
  "https://gamestats.ai/api/v1/accounts/{account_id}/achievement_events"

Create an Achievement Image

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
achievement_name formData string Sí The name of the achievement to attach the image to
image formData file Sí The image of the achievement

Respuestas

  • 201 achievement image created
post /api/v1/accounts/{account_id}/achievement_images
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -F "achievement_name=string" \
  -F "image=@/path/to/image.png" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/achievement_images"

List achievement reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 achievement reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/achievement_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/achievement_reports"

Ejemplo de respuesta

[
  {
    "id": 12,
    "label": "Achievements",
    "description": "Unlock counts and rates for every achievement."
  },
  {
    "id": 24,
    "label": "Rare Achievements",
    "description": "Achievements unlocked by the fewest players."
  }
]

Show an achievement report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
page query integer No Page of report rows to return (1-based, defaults to 1). The response `pagination` object reports the current `page`, total row `count`, and total number of `pages`; request pages 1..`pages` to read the full report.

Respuestas

  • 200 achievement report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/achievement_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/achievement_reports/{id}?page=2"

Ejemplo de respuesta

{
  "id": 12,
  "label": "Achievements",
  "description": "Unlock counts and rates for every achievement.",
  "metrics": [
    {
      "label": "# of Players Unlocked",
      "format": "unformatted"
    },
    {
      "label": "% of Players",
      "format": "percentage"
    }
  ],
  "filters": [],
  "rows": [
    {
      "subject": "First Blood",
      "values": [
        {
          "metric": "# of Players Unlocked",
          "value": 1240
        },
        {
          "metric": "% of Players",
          "value": 0.82
        }
      ]
    },
    {
      "subject": "Flawless Victory",
      "values": [
        {
          "metric": "# of Players Unlocked",
          "value": 356
        },
        {
          "metric": "% of Players",
          "value": 0.24
        }
      ]
    },
    {
      "subject": "All 2 achievements",
      "values": [
        {
          "metric": "# of Players Unlocked",
          "value": 312
        },
        {
          "metric": "% of Players",
          "value": 0.21
        }
      ]
    }
  ]
}

Creates an Achievement

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Cuerpo de la solicitud (JSON)

Campo Tipo Obligatorio Descripción
name string Sí The name of the achievement. Adding an achievement that no player has unlocked yet lets it count toward your completion rates. Sending the same name again returns the existing achievement.

Respuestas

  • 201 achievement created
  • 422 invalid request
post /api/v1/accounts/{account_id}/achievements
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "First Blood"
}' \
  "https://gamestats.ai/api/v1/accounts/{account_id}/achievements"

List a player's unlocked achievements

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
username query string Sí The player's username.
page query integer No Page of unlocks to return (1-based, defaults to 1). The response `pagination` object reports the current `page`, total `count`, and total number of `pages`.

Respuestas

  • 200 player's unlocked achievements returned
  • 404 player not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/players/achievements
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/players/achievements?username=hero&page=2"

Ejemplo de respuesta

{
  "achievement_unlocks": [
    {
      "achievement": "First Blood",
      "occurred_at": "2026-01-15T10:22:00Z"
    },
    {
      "achievement": "First Blood",
      "occurred_at": "2026-01-02T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "count": 2,
    "pages": 1
  }
}

Archetypes

Group characters into play-style archetypes for reports.

List archetype reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 archetype reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/archetype_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/archetype_reports"

Ejemplo de respuesta

[
  {
    "id": 12,
    "label": "Win Rate by Archetype",
    "description": "Win rate for each play-style archetype."
  },
  {
    "id": 23,
    "label": "Pick Rate by Archetype",
    "description": "How often each archetype is played."
  }
]

Show an archetype report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
page query integer No Page of report rows to return (1-based, defaults to 1). The response `pagination` object reports the current `page`, total row `count`, and total number of `pages`; request pages 1..`pages` to read the full report.
version_id query array No Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array No Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array No Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array No Minimum and maximum bounds for the report threshold filter, as [min, max].

Respuestas

  • 200 archetype report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/archetype_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/archetype_reports/{id}?page=2"

Ejemplo de respuesta

{
  "id": 12,
  "label": "Win Rate by Archetype",
  "description": "Win rate for each play-style archetype.",
  "metrics": [
    {
      "label": "Win Rate",
      "format": "percentage"
    }
  ],
  "filters": [
    {
      "name": "version_id",
      "type": "category",
      "label": "Version",
      "values": [
        {
          "value": "1",
          "label": "1.0"
        }
      ]
    },
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    }
  ],
  "rows": [
    {
      "subject": "Ryu, Ken, Akuma",
      "values": [
        {
          "metric": "Win Rate",
          "value": 0.56
        }
      ]
    },
    {
      "subject": "Zangief, Birdie",
      "values": [
        {
          "metric": "Win Rate",
          "value": 0.47
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "count": 2,
    "pages": 1
  }
}

Events

Track any in-game event and report on the properties you send with it.

The events endpoint should be called whenever an in-game event you want to track occurs. Event names, versions, and players are created automatically the first time they are sent. The event attributes bag is a free-form set of string, number, or boolean values that you can report on later.

List event reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 event reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/event_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/event_reports"

Ejemplo de respuesta

[
  {
    "id": 12,
    "label": "Damage by Form",
    "description": "Total damage broken down by combat form."
  },
  {
    "id": 15,
    "label": "Ability Uses by Zone",
    "description": "How often abilities are used in each zone."
  }
]

Create an event report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Cuerpo de la solicitud (JSON)

Campo Tipo Obligatorio Descripción
event_report object No

Respuestas

  • 201 event report created
  • 422 invalid request
  • 401 unauthorized
post /api/v1/accounts/{account_id}/event_reports
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "event_report": {
    "external_id": "string",
    "event_name": "string",
    "event_name_id": 0,
    "group_by_attribute": "string",
    "group_by_date": false,
    "label": "string",
    "description": "string",
    "default_recent_days": 0,
    "report_metrics_attributes": [
      {
        "attribute_type_id": 0,
        "attribute_name": "string",
        "metric_type": "string",
        "label": "string",
        "number_format": "string",
        "number_precision": 0,
        "use_for_sorting": false
      }
    ],
    "report_filters_attributes": [
      {
        "attribute_type_id": 0,
        "attribute_name": "string",
        "filter_type": "string",
        "label": "string",
        "default_values": [
          "string"
        ],
        "buckets": [
          0
        ]
      }
    ],
    "report_threshold_filter_attributes": {
      "label": "string",
      "default_minimum": 0,
      "default_maximum": 0
    }
  }
}' \
  "https://gamestats.ai/api/v1/accounts/{account_id}/event_reports"

Ejemplo de respuesta

{
  "id": 12,
  "external_id": "damage_by_form",
  "label": "Damage by Form",
  "description": "Total damage broken down by combat form."
}

Show an event report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
page query integer No Page of report rows to return (1-based, defaults to 1). The response `pagination` object reports the current `page`, total row `count`, and total number of `pages`; request pages 1..`pages` to read the full report.
version_id query array No Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array No Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array No Minimum and maximum bounds for the report threshold filter, as [min, max].

Respuestas

  • 200 event report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/event_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/event_reports/{id}?page=2"

Ejemplo de respuesta

{
  "id": 12,
  "external_id": "damage_by_form",
  "label": "Damage by Form",
  "description": "Total damage broken down by combat form.",
  "report_metrics": [
    {
      "id": 34,
      "attribute_name": null,
      "metric_type": "count_",
      "label": "Uses",
      "number_format": "unformatted",
      "number_precision": 0,
      "use_for_sorting": false
    },
    {
      "id": 35,
      "attribute_name": "damage",
      "metric_type": "sum_",
      "label": "Total Damage",
      "number_format": "unformatted",
      "number_precision": 0,
      "use_for_sorting": true
    }
  ],
  "report_filters": [
    {
      "id": 21,
      "attribute_name": "result",
      "filter_type": "category",
      "label": "Result"
    }
  ],
  "metrics": [
    {
      "label": "Uses",
      "format": "unformatted"
    },
    {
      "label": "Total Damage",
      "format": "unformatted"
    }
  ],
  "filters": [
    {
      "name": "version_id",
      "type": "category",
      "label": "Version",
      "values": [
        {
          "value": "1",
          "label": "1.0"
        }
      ]
    },
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    }
  ],
  "rows": [
    {
      "subject": "Cow",
      "values": [
        {
          "metric": "Uses",
          "value": 512
        },
        {
          "metric": "Total Damage",
          "value": 8123
        }
      ]
    },
    {
      "subject": "Deer",
      "values": [
        {
          "metric": "Uses",
          "value": 431
        },
        {
          "metric": "Total Damage",
          "value": 5210
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "count": 2,
    "pages": 1
  }
}

Update an event report

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.

Cuerpo de la solicitud (JSON)

Campo Tipo Obligatorio Descripción
event_report object No

Respuestas

  • 200 event report updated
  • 422 invalid request
  • 404 report not found
  • 401 unauthorized
patch /api/v1/accounts/{account_id}/event_reports/{id}
Requiere autenticación 
curl \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "event_report": {
    "external_id": "string",
    "event_name": "string",
    "event_name_id": 0,
    "group_by_attribute": "string",
    "group_by_date": false,
    "label": "string",
    "description": "string",
    "default_recent_days": 0,
    "report_metrics_attributes": [
      {
        "id": 0,
        "_destroy": false,
        "attribute_type_id": 0,
        "attribute_name": "string",
        "metric_type": "string",
        "label": "string",
        "number_format": "string",
        "number_precision": 0,
        "use_for_sorting": false
      }
    ],
    "report_filters_attributes": [
      {
        "id": 0,
        "_destroy": false,
        "attribute_type_id": 0,
        "attribute_name": "string",
        "filter_type": "string",
        "label": "string",
        "default_values": [
          "string"
        ],
        "buckets": [
          0
        ]
      }
    ],
    "report_threshold_filter_attributes": {
      "id": 0,
      "_destroy": false,
      "label": "string",
      "default_minimum": 0,
      "default_maximum": 0
    }
  }
}' \
  "https://gamestats.ai/api/v1/accounts/{account_id}/event_reports/{id}"

Ejemplo de respuesta

{
  "id": 12,
  "external_id": "damage_by_form",
  "label": "Damage by Combat Form",
  "description": "Total damage broken down by combat form."
}

Creates an Event

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Cuerpo de la solicitud (JSON)

Campo Tipo Obligatorio Descripción
event_name string Sí The name of the event, e.g. "form_session" or "ability_used".
version_name string Sí The event in this request corresponds to this version name.
player_username string No The username for the player. Optional: omit for playerless telemetry.
occurred_at string Sí This represents the time the event occurs.
event_attributes object No A free-form bag of string, number, or boolean values describing the event. Numeric strings are coerced to numbers.
idempotency_key string No Optional. A unique key for this event, such as your own record id. If an event with the same key was already received, the request is accepted but no duplicate event is created, so retries are safe.

Respuestas

  • 201 event queued for creation
  • 402 monthly tracked record limit reached
  • 422 invalid request
post /api/v1/accounts/{account_id}/events
Requiere autenticación 
curl \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "event_name": "ability_used",
  "version_name": "1.0",
  "player_username": "a_player_123",
  "occurred_at": "2022-08-09T23:26:01UTC",
  "event_attributes": {
    "form": "Cow",
    "ability": "Stampede",
    "times_used": 3,
    "damage_ratio": 1.8,
    "ranked": true
  },
  "idempotency_key": "ability-used-8f14e45f"
}' \
  "https://gamestats.ai/api/v1/accounts/{account_id}/events"

Players

Manage players. Applies across all game modules.

Rename a Player

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Cuerpo de la solicitud (JSON)

Campo Tipo Obligatorio Descripción
username string Sí The player's current username.
new_username string Sí The player's new username. Must be unique within the account.

Respuestas

  • 200 player renamed
  • 404 player not found
  • 422 new username is blank
  • 401 unauthorized
patch /api/v1/accounts/{account_id}/players/rename
Requiere autenticación 
curl \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "old_username",
  "new_username": "new_username"
}' \
  "https://gamestats.ai/api/v1/accounts/{account_id}/players/rename"

List retention reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 retention reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/retention_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/retention_reports"

Ejemplo de respuesta

[
  {
    "id": 31,
    "label": "Player Retention",
    "description": "Day 1, 7, and 30 retention for new players."
  }
]

Show a retention report

Returns one entry in cohorts per first-seen day, newest first. A cohort is the players whose first activity (a match, achievement unlock, progression event, or event) fell on that UTC day. Each cohort has its new players and the share of them active again exactly 1, 7, and 30 days later. A retention value is null until that day has finished. average_retention averages each day over every cohort with a finished value, weighted by cohort size. daily_active_players, weekly_active_players, monthly_active_players, and stickiness have one entry for each finished day from the first activity in the range. Weekly and monthly active players on a day are the players active in the 7 and 30 days ending that day, and stickiness is daily active players divided by monthly active players (null when there are none). averages averages each of the four over those days. Without date filters, the report covers cohorts from the last 90 days.

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
occurred_between query array No Two ISO dates (from, to) that limit the cohorts and active player days to that range. Leave either blank for an open range.
occurred_after query array No Only include cohorts from the last N days. Allowed values: 1, 7, 30. Takes precedence over the start of `occurred_between`.

Respuestas

  • 200 retention report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/retention_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/retention_reports/{id}"

Ejemplo de respuesta

{
  "id": 31,
  "label": "Player Retention",
  "description": "Day 1, 7, and 30 retention for new players.",
  "filters": [
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    },
    {
      "name": "occurred_between",
      "type": "range",
      "label": "Date range",
      "values": []
    }
  ],
  "cohorts": [
    {
      "first_seen_on": "2026-10-12",
      "new_players": 140,
      "day_1_retention": 0.41,
      "day_7_retention": null,
      "day_30_retention": null
    },
    {
      "first_seen_on": "2026-09-01",
      "new_players": 212,
      "day_1_retention": 0.38,
      "day_7_retention": 0.17,
      "day_30_retention": 0.06
    }
  ],
  "average_retention": {
    "day_1": 0.39,
    "day_7": 0.16,
    "day_30": 0.06
  },
  "daily_active_players": [
    {
      "date": "2026-10-12",
      "players": 1250
    },
    {
      "date": "2026-10-13",
      "players": 1312
    }
  ],
  "weekly_active_players": [
    {
      "date": "2026-10-12",
      "players": 4120
    },
    {
      "date": "2026-10-13",
      "players": 4185
    }
  ],
  "monthly_active_players": [
    {
      "date": "2026-10-12",
      "players": 8410
    },
    {
      "date": "2026-10-13",
      "players": 8460
    }
  ],
  "stickiness": [
    {
      "date": "2026-10-12",
      "value": 0.149
    },
    {
      "date": "2026-10-13",
      "value": 0.155
    }
  ],
  "averages": {
    "daily_active_players": 1281.0,
    "weekly_active_players": 4152.5,
    "monthly_active_players": 8435.0,
    "stickiness": 0.152
  }
}

List revenue reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 revenue reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/revenue_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/revenue_reports"

Ejemplo de respuesta

[
  {
    "id": 42,
    "label": "Revenue",
    "description": "Purchases from the purchase event, in US dollars."
  }
]

Show a revenue report

Revenue comes from the report's revenue_sources: for each source, the amount attribute of its event is added up in US dollars (currency), and negative amounts count as refunds. daily has one entry for each finished UTC day from the first activity in the range, with revenue from every source, paying players (players with revenue from a source with paid_by_player), ARPDAU (revenue divided by active players), payer conversion (paying players divided by active players), ARPPU (revenue from paid_by_player sources divided by paying players), and revenue_by_source, keyed by source label. A player is active on a day when they play a match, unlock an achievement, record a progression event, or send an event. cohorts has one entry per first-seen day, newest first, with its new players and the revenue from every source per new player from their first day through day 1, 7, and 30, which is null until that day has finished. averages has the average daily revenue, ARPDAU, payer conversion, and ARPPU over the days (weighted by active and paying player-days), and the revenue per new player over every finished cohort, weighted by cohort size. Without date filters, the report covers the last 90 days.

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
occurred_between query array No Two ISO dates (from, to) that limit the cohorts and days to that range. Leave either blank for an open range.
occurred_after query array No Only include the last N days. Allowed values: 1, 7, 30. Takes precedence over the start of `occurred_between`.

Respuestas

  • 200 revenue report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/revenue_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/revenue_reports/{id}"

Ejemplo de respuesta

{
  "id": 42,
  "label": "Revenue",
  "description": "Purchases and ad revenue, in US dollars.",
  "currency": "USD",
  "revenue_sources": [
    {
      "label": "In-app purchases",
      "event_name": "purchase",
      "attribute_name": "amount_usd",
      "paid_by_player": true
    },
    {
      "label": "Ads",
      "event_name": "ad_revenue",
      "attribute_name": "revenue_usd",
      "paid_by_player": false
    }
  ],
  "filters": [
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    },
    {
      "name": "occurred_between",
      "type": "range",
      "label": "Date range",
      "values": []
    }
  ],
  "cohorts": [
    {
      "first_seen_on": "2026-10-12",
      "new_players": 140,
      "revenue_per_player_by_day_1": 0.21,
      "revenue_per_player_by_day_7": null,
      "revenue_per_player_by_day_30": null
    },
    {
      "first_seen_on": "2026-09-01",
      "new_players": 212,
      "revenue_per_player_by_day_1": 0.18,
      "revenue_per_player_by_day_7": 0.54,
      "revenue_per_player_by_day_30": 1.12
    }
  ],
  "daily": [
    {
      "date": "2026-10-12",
      "revenue": 612.5,
      "paying_players": 31,
      "arpdau": 0.049,
      "payer_conversion": 0.0248,
      "arppu": 16.92,
      "revenue_by_source": {
        "In-app purchases": 524.5,
        "Ads": 88.0
      }
    },
    {
      "date": "2026-10-13",
      "revenue": 540.0,
      "paying_players": 27,
      "arpdau": 0.041,
      "payer_conversion": 0.0206,
      "arppu": 17.04,
      "revenue_by_source": {
        "In-app purchases": 460.0,
        "Ads": 80.0
      }
    }
  ],
  "averages": {
    "daily_revenue": 576.25,
    "arpdau": 0.045,
    "payer_conversion": 0.0227,
    "arppu": 16.97,
    "revenue_per_player_by_day_1": 0.19,
    "revenue_per_player_by_day_7": 0.54,
    "revenue_per_player_by_day_30": 1.12
  }
}

List session reports

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.

Respuestas

  • 200 session reports listed
  • 401 unauthorized
get /api/v1/accounts/{account_id}/session_reports
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/session_reports"

Ejemplo de respuesta

[
  {
    "id": 43,
    "label": "Sessions",
    "description": "Session length and daily playtime."
  }
]

Show a session report

Sessions come from the report's events, as set by session_tracking. With duration, each event_name event is one session and duration_attribute_name holds its length in seconds. With start_and_end, an end_event_name event closes a session when the same player's previous start or end event was an event_name event; a start without an end is not counted. A session counts on the UTC day it starts, and sessions longer than 24 hours or without a positive length are left out. daily has one entry for each finished UTC day from the first activity in the range, with sessions, the average session length in minutes, and sessions and playtime in minutes per active player. A player is active on a day when they play a match, unlock an achievement, record a progression event, send an event, or start a session. length_ranges counts the sessions in those days by length, starting at from_minutes. averages has the average daily sessions, and the session length, sessions per player, and playtime per player over all those days, weighted by sessions and active player-days. Without date filters, the report covers the last 90 days.

Parámetros

Nombre En Tipo Obligatorio Descripción
account_id path integer Sí Your account ID.
id path integer Sí The report ID.
occurred_between query array No Two ISO dates (from, to) that limit the days to that range. Leave either blank for an open range.
occurred_after query array No Only include the last N days. Allowed values: 1, 7, 30. Takes precedence over the start of `occurred_between`.

Respuestas

  • 200 session report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/session_reports/{id}
Requiere autenticación 
curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $GAMESTATS_API_TOKEN" \
  "https://gamestats.ai/api/v1/accounts/{account_id}/session_reports/{id}"

Ejemplo de respuesta

{
  "id": 43,
  "label": "Sessions",
  "description": "Session length and daily playtime.",
  "session_tracking": "start_and_end",
  "event_name": "session_start",
  "duration_attribute_name": null,
  "end_event_name": "session_end",
  "filters": [
    {
      "name": "occurred_after",
      "type": "category",
      "label": "From",
      "values": [
        {
          "value": "7",
          "label": "Last 7 days"
        }
      ]
    },
    {
      "name": "occurred_between",
      "type": "range",
      "label": "Date range",
      "values": []
    }
  ],
  "length_ranges": [
    {
      "label": "Under 1 min",
      "from_minutes": 0,
      "sessions": 412,
      "share_of_sessions": 0.103
    },
    {
      "label": "1 to 3 min",
      "from_minutes": 1,
      "sessions": 1288,
      "share_of_sessions": 0.322
    }
  ],
  "daily": [
    {
      "date": "2026-10-12",
      "sessions": 2010,
      "average_session_length_minutes": 4.6,
      "sessions_per_player": 3.4,
      "playtime_per_player_minutes": 15.6
    },
    {
      "date": "2026-10-13",
      "sessions": 1990,
      "average_session_length_minutes": 4.4,
      "sessions_per_player": 3.3,
      "playtime_per_player_minutes": 14.5
    }
  ],
  "averages": {
    "daily_sessions": 2000.0,
    "session_length_minutes": 4.5,
    "sessions_per_player": 3.35,
    "playtime_per_player_minutes": 15.05
  }
}