Skip to main content
POST
/
user
/
matches
curl -X POST https://teambattles.gg/api/v1/user/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"excludeStatuses": ["PENDING", "COMPLETED"], "limit": 25}'

{
  "matches": [
    {
      "id": "<string>",
      "status": "PENDING",
      "game": {
        "id": "<string>",
        "nameKey": "<string>"
      },
      "gameMode": "<string>",
      "creatorTeam": {
        "id": "<string>",
        "name": "<string>",
        "tag": "<string>"
      },
      "acceptedTeam": {
        "id": "<string>",
        "name": "<string>",
        "tag": "<string>"
      },
      "scheduledAt": "2023-11-07T05:31:56Z",
      "startedAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "bestOf": 123
    }
  ],
  "count": 123,
  "pagination": {
    "cursor": "<string>",
    "hasMore": true
  },
  "timestamp": "2023-11-07T05:31:56Z"
}
curl -X POST https://teambattles.gg/api/v1/user/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"excludeStatuses": ["PENDING", "COMPLETED"], "limit": 25}'

​
Permission Required

This endpoint requires the matches.user_matches permission on your API key.

​
What’s Returned

This endpoint returns matches where you are on the roster - meaning you were specifically added as a player for that match. Being a member of a team is not enough; you must be on the actual match roster.
If you’re a team member but weren’t added to a specific match’s roster, that match won’t appear in your results.

​
Filtering Options

​
Status Filtering

You can filter matches by their status using two mutually exclusive parameters:
  • includeStatuses: Only return matches with these statuses (takes precedence)
  • excludeStatuses: Return all matches except those with these statuses

​
Date Filtering

Filter by scheduled or creation dates using ISO 8601 format:
  • scheduledAfter / scheduledBefore: Filter by scheduled match time
  • createdAfter / createdBefore: Filter by when the match was created

​
Other Filters

  • gameId: Filter by a specific game
  • opponentId: Filter by opponent team (accepts team ID or slug)

​
Pagination

Results are paginated with a default of 25 matches per page (maximum 100).
ParameterTypeDescription
limitnumberResults per page (1-100, default 25)
cursorstringCursor from previous response for next page
The response includes a pagination object: 
{
  "pagination": {
    "cursor": "eyJpZCI6Im1hdGNoXzEyMyIsInRzIjoxNzA0MDY3MjAwfQ==",
    "hasMore": true
  }
}

​
Match Statuses

StatusDescription
PENDINGMatch is waiting for an opponent to accept
ACCEPTEDMatch has been accepted, waiting for players to be ready
READYAll players are ready, match can be started
IN_PROGRESSMatch is currently being played
COMPLETEDMatch has finished normally
CANCELLEDMatch was cancelled before completion
DISPUTEDMatch result is being disputed
FORFEITEDOne team forfeited the match

​
Common Use Cases

​
Get Active Matches Only

Filter out pending and completed matches to show only active ones: 
{
  "excludeStatuses": ["PENDING", "COMPLETED", "CANCELLED", "FORFEITED"],
  "limit": 25
}

​
Get Matches in a Date Range

{
  "scheduledAfter": "2024-01-01T00:00:00Z",
  "scheduledBefore": "2024-12-31T23:59:59Z",
  "limit": 50
}

​
Get Matches Against a Specific Opponent

{
  "opponentId": "Team_Alpha",
  "includeStatuses": ["COMPLETED"]
}

​
Paginate Through All Matches

{
  "limit": 25,
  "cursor": "eyJpZCI6Im1hdGNoXzEyMyIsInRzIjoxNzA0MDY3MjAwfQ=="
}

Authorizations

​
Authorization
string
header
required

API key authentication. Generate an API key from Settings > Developer in the TeamBattles app. Format: tb_xxxxxxxx...

Body

application/json

Optional filters and pagination options

​
includeStatuses
enum<string>[]

Only include matches with these statuses. Takes precedence over excludeStatuses.

Current status of a match

Available options:
PENDING,
ACCEPTED,
READY,
IN_PROGRESS,
COMPLETED,
CANCELLED,
DISPUTED,
FORFEITED
​
excludeStatuses
enum<string>[]

Exclude matches with these statuses. Ignored if includeStatuses is provided.

Current status of a match

Available options:
PENDING,
ACCEPTED,
READY,
IN_PROGRESS,
COMPLETED,
CANCELLED,
DISPUTED,
FORFEITED
​
gameId
string

Filter by game ID

​
scheduledAfter
string<date-time>

Filter to matches scheduled after this date (ISO 8601)

​
scheduledBefore
string<date-time>

Filter to matches scheduled before this date (ISO 8601)

​
createdAfter
string<date-time>

Filter to matches created after this date (ISO 8601)

​
createdBefore
string<date-time>

Filter to matches created before this date (ISO 8601)

​
opponentId
string

Filter by opponent team (ID or slug)

​
limit
integer
default:25

Maximum number of matches to return (1-100)

Required range: 1 <= x <= 100
​
cursor
string

Pagination cursor from previous response

Response

Successful response

​
matches
object[]
​
count
integer

Number of matches returned in this page

​
pagination
object
​
timestamp
string<date-time>

Response timestamp (ISO 8601)