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"], "numItems": 25}'

{
  "page": [
    {
      "id": "<string>",
      "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
    }
  ],
  "isDone": true,
  "continueCursor": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://teambattles.gg/docs/llms.txt

Use this file to discover all available pages before exploring further.

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"], "numItems": 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).

​
Request Fields

ParameterTypeDescription
numItemsnumberNumber of items per page, 1-100, default 25
cursorstringOpaque cursor string from a prior response (optional)

​
Response Fields

FieldTypeDescription
pagearrayArray of matches for this page
isDonebooleantrue when there are no more pages to fetch
continueCursorstringPass back as cursor on the next request
Example response envelope: 
{
	"page": [],
	"isDone": false,
	"continueCursor": "eyJpZCI6Im1hdGNoXzEyMyIsInRzIjoxNzA0MDY3MjAwfQ=="
}

​
Errors

CodeHTTP StatusWhen
error_api_key_required401Missing Authorization header
error_api_key_invalid401API key is unknown, revoked, or expired
error_api_key_permission_denied403The key does not hold matches.user_matches: read
error_invalid_num_items400numItems is outside the allowed 1-100 range
error_invalid_limit400Reserved for limit-style page sizes (registry-level error code)
error_invalid_cursor400cursor is malformed or no longer valid
error_invalid_date_format400One of the scheduled*/created* filters is not ISO 8601
error_team_not_found404opponentId could not be resolved to a team
error_internal500Unhandled server error - retry or contact support

​
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"],
	"numItems": 25
}

​
Get Matches in a Date Range

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

​
Get Matches Against a Specific Opponent

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

​
Paginate Through All Matches

{
	"numItems": 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)

​
numItems
integer
default:25

Maximum number of matches to return (1-100)

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

Pagination cursor from previous response (opaque Convex cursor string)

Response

Successful response

​
page
object[]
required
​
isDone
boolean
required
​
continueCursor
string
required