Skip to main content
POST
/
game
/
matches
curl -X POST https://teambattles.gg/api/v1/game/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"IN_PROGRESS","limit":25}'

{
  "matches": [
    {
      "id": "<string>",
      "gameMode": "<string>",
      "bestOf": 0,
      "creatorTeam": {
        "id": "<string>",
        "name": "<string>",
        "tag": "<string>",
        "avatarUrl": "<string>"
      },
      "acceptedTeam": {
        "id": "<string>",
        "name": "<string>",
        "tag": "<string>",
        "avatarUrl": "<string>"
      },
      "creatorTeamScore": 0,
      "acceptedTeamScore": 0,
      "scheduledAt": "<string>",
      "startedAt": "<string>",
      "completedAt": "<string>",
      "createdAt": "<string>"
    }
  ],
  "count": 0,
  "pagination": {
    "cursor": "<string>",
    "hasMore": true
  },
  "timestamp": "<string>"
}

​
Permission Required

This endpoint requires the game.lifecycle permission with read access. Your API key must be a game-developer key bound to a game. Although it is a POST, this operation is a filtered read - it never mutates. The game is derived from the key’s bound game (never a body field), so a key bound to game X can only ever list game-X matches. A non-developer key, or a key with no bound game, receives a 403 error_game_scope_mismatch.

​
Access / Membership Rules

There is no per-match binding here (the call spans many matches); the bound game is the only scope boundary, applied in the handler. A limit outside 1-100 returns 400 error_invalid_limit.

​
What’s Returned

Returns { matches, count, pagination, timestamp }. Each matches[] entry carries id, status, gameMode, bestOf, both teams, the aggregate scores, and the ISO lifecycle timestamps. pagination is a legacy cursor page: pass pagination.cursor back unchanged as the next request’s cursor and stop when pagination.hasMore is false.

​
Request Body

All fields are optional - an empty body returns the first page.
FieldTypeRequiredDescription
statusstringNoFilter by MatchStatus (e.g. IN_PROGRESS).
limitnumberNoPage size, 1-100. Defaults to the handler’s internal default.
cursorstringNoOpaque continuation cursor from a prior page’s pagination.cursor.
curl -X POST https://teambattles.gg/api/v1/game/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"IN_PROGRESS","limit":25}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Body

application/json

Status filter and cursor pagination for listing the bound key's game matches. The game is derived from the developer-app key's bound game (not a body field).

​
status
string

Optional MatchStatus filter (e.g. IN_PROGRESS).

​
limit
number

Page size (1-100, enforced by the handler). Defaults to the handler's internal default.

​
cursor
string

Opaque continuation cursor from a prior page's pagination.cursor.

Response

Legacy cursor-paginated result. pagination.cursor is null when there are no more pages.

​
matches
object[]
required
​
count
integer
required
Required range: -9007199254740991 <= x <= 9007199254740991
​
pagination
object
required
​
timestamp
string
required