Logo

API-documentatie

Arrow left Terug naar de app

API-documentatie

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.

Basis-URL: 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

Antwoorden

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

Voorbeeldantwoord

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

Show the authenticated user

Antwoorden

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

Pings the API

Antwoorden

  • 201 ping received
post /api/v1/pings
Authenticatie vereist 
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.

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
page query integer Nee 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 Nee Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array Nee Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array Nee Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array Nee Minimum and maximum bounds for the report threshold filter, as [min, max].

Antwoorden

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

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
page query integer Nee 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 Nee Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array Nee Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array Nee Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array Nee Minimum and maximum bounds for the report threshold filter, as [min, max].

Antwoorden

  • 200 character attribute report returned
  • 404 report not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/character_attribute_reports/{id}
Authenticatie vereist 
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"

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
character_external_id formData string Ja The external ID you used in the Characters API
image formData file Ja The image of the character

Antwoorden

  • 201 character image created
post /api/v1/accounts/{account_id}/character_images
Authenticatie vereist 
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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
page query integer Nee 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 Nee Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array Nee Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array Nee Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array Nee Minimum and maximum bounds for the report threshold filter, as [min, max].

Antwoorden

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

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Aanvraaginhoud (JSON)

Veld Type Verplicht Omschrijving
external_id string Ja 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 Ja The name of the character. This does not currently vary from version to version.
description string Nee 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 Ja The attributes in this request correspond to this version name. Character attributes can vary from version to version.
character_attributes object Nee Key-value pairs. These are displayed in reports and can be configured as filters.

Antwoorden

  • 201 character for version queued for creation
  • 422 invalid request
post /api/v1/accounts/{account_id}/characters
Authenticatie vereist 
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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Aanvraaginhoud (JSON)

Veld Type Verplicht Omschrijving
external_id string Nee 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 Ja The match in this request corresponds to this version name.
match_at string Nee The match in this request corresponds to this version name.
match_attributes object Nee
match_players object[] Nee

Antwoorden

  • 201 match queued for creation
  • 402 monthly tracked record limit reached
  • 422 invalid request
post /api/v1/accounts/{account_id}/matches
Authenticatie vereist 
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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
page query integer Nee 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 Nee Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array Nee Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array Nee Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array Nee Minimum and maximum bounds for the report threshold filter, as [min, max].

Antwoorden

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

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Aanvraaginhoud (JSON)

Veld Type Verplicht Omschrijving
version_name string Ja The progression event in this request corresponds to this version name.
player_username string Ja The username for the player.
progression_name string Ja
progression_type_name string Ja
progression_milestone_name string Ja If not provided, the milestone name will be the same as the milestone type name.
progression_milestone_type_name string Ja
is_new_instance boolean Nee 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 Nee If provided, the progression event in this request is considered the start of a new instances occurring at this time.
time_elapsed integer Nee 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 Ja This represents the time the event occurs.

Antwoorden

  • 201 progression event queued for creation
  • 402 monthly tracked record limit reached
  • 422 invalid request
post /api/v1/accounts/{account_id}/progression_events
Authenticatie vereist 
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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
page query integer Nee 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 Nee Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array Nee Only include data from the last N days. Allowed values: 1, 7, 30.

Antwoorden

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

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Aanvraaginhoud (JSON)

Veld Type Verplicht Omschrijving
version_name string Ja The achievement unlock in this request corresponds to this version name.
player_username string Ja The username for the player.
achievement_name string Ja The name of the achievement the player unlocked. Achievements are created automatically the first time they are sent.
occurred_at string Ja This represents the time the player unlocked the achievement. Sending the same achievement for the same player again has no effect.

Antwoorden

  • 201 achievement event queued for creation
  • 402 monthly tracked record limit reached
  • 422 invalid request
post /api/v1/accounts/{account_id}/achievement_events
Authenticatie vereist 
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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
achievement_name formData string Ja The name of the achievement to attach the image to
image formData file Ja The image of the achievement

Antwoorden

  • 201 achievement image created
post /api/v1/accounts/{account_id}/achievement_images
Authenticatie vereist 
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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
page query integer Nee 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.

Antwoorden

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

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Aanvraaginhoud (JSON)

Veld Type Verplicht Omschrijving
name string Ja 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.

Antwoorden

  • 201 achievement created
  • 422 invalid request
post /api/v1/accounts/{account_id}/achievements
Authenticatie vereist 
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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
username query string Ja The player's username.
page query integer Nee 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`.

Antwoorden

  • 200 player's unlocked achievements returned
  • 404 player not found
  • 401 unauthorized
get /api/v1/accounts/{account_id}/players/achievements
Authenticatie vereist 
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"

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
page query integer Nee 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 Nee Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
event_type_id query array Nee Filter to one or more event type IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array Nee Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array Nee Minimum and maximum bounds for the report threshold filter, as [min, max].

Antwoorden

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

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Aanvraaginhoud (JSON)

Veld Type Verplicht Omschrijving
event_report object Nee

Antwoorden

  • 201 event report created
  • 422 invalid request
  • 401 unauthorized
post /api/v1/accounts/{account_id}/event_reports
Authenticatie vereist 
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"

Voorbeeldantwoord

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

Show an event report

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
page query integer Nee 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 Nee Filter to one or more game version IDs. Discover valid IDs from the `filters` in the response.
occurred_after query array Nee Only include data from the last N days. Allowed values: 1, 7, 30.
threshold query array Nee Minimum and maximum bounds for the report threshold filter, as [min, max].

Antwoorden

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

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.

Aanvraaginhoud (JSON)

Veld Type Verplicht Omschrijving
event_report object Nee

Antwoorden

  • 200 event report updated
  • 422 invalid request
  • 404 report not found
  • 401 unauthorized
patch /api/v1/accounts/{account_id}/event_reports/{id}
Authenticatie vereist 
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}"

Voorbeeldantwoord

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

Creates an Event

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Aanvraaginhoud (JSON)

Veld Type Verplicht Omschrijving
event_name string Ja The name of the event, e.g. "form_session" or "ability_used".
version_name string Ja The event in this request corresponds to this version name.
player_username string Nee The username for the player. Optional: omit for playerless telemetry.
occurred_at string Ja This represents the time the event occurs.
event_attributes object Nee A free-form bag of string, number, or boolean values describing the event. Numeric strings are coerced to numbers.
idempotency_key string Nee 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.

Antwoorden

  • 201 event queued for creation
  • 402 monthly tracked record limit reached
  • 422 invalid request
post /api/v1/accounts/{account_id}/events
Authenticatie vereist 
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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Aanvraaginhoud (JSON)

Veld Type Verplicht Omschrijving
username string Ja The player's current username.
new_username string Ja The player's new username. Must be unique within the account.

Antwoorden

  • 200 player renamed
  • 404 player not found
  • 422 new username is blank
  • 401 unauthorized
patch /api/v1/accounts/{account_id}/players/rename
Authenticatie vereist 
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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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.

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
occurred_between query array Nee 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 Nee Only include cohorts from the last N days. Allowed values: 1, 7, 30. Takes precedence over the start of `occurred_between`.

Antwoorden

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

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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.

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
occurred_between query array Nee 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 Nee Only include the last N days. Allowed values: 1, 7, 30. Takes precedence over the start of `occurred_between`.

Antwoorden

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

Voorbeeldantwoord

{
  "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

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.

Antwoorden

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

Voorbeeldantwoord

[
  {
    "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.

Parameters

Naam In Type Verplicht Omschrijving
account_id path integer Ja Your account ID.
id path integer Ja The report ID.
occurred_between query array Nee Two ISO dates (from, to) that limit the days to that range. Leave either blank for an open range.
occurred_after query array Nee Only include the last N days. Allowed values: 1, 7, 30. Takes precedence over the start of `occurred_between`.

Antwoorden

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

Voorbeeldantwoord

{
  "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
  }
}