Skip to main content
POST
/
teams
/
{identifier}
/
matches
curl -X POST https://teambattles.gg/api/v1/teams/Team_Alpha/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"excludeStatuses": ["CANCELLED", "FORFEITED"], "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/teams/Team_Alpha/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"excludeStatuses": ["CANCELLED", "FORFEITED"], "limit": 25}'

​
Permission Required

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

​
Membership Required

You must be an active member of the team to access its matches. If you’re not a member, you’ll receive a 403 error with code error_team_membership_required.

​
Team Identifier

The {identifier} path parameter accepts either:
  • Team ID: The Convex document ID (e.g., jh7abc123def456)
  • Team Slug: The URL-friendly team name (e.g., Team_Alpha)
The slug is derived from the team name by replacing spaces with underscores.

​
Filtering Options

​
Status Filtering

Filter matches by their status:
  • 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

​
Common Use Cases

​
Get Active Team Matches

{
  "excludeStatuses": ["PENDING", "COMPLETED", "CANCELLED", "FORFEITED"],
  "limit": 25
}

​
Get Matches Against a Specific Opponent

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

​
Get Upcoming Scheduled Matches

{
  "scheduledAfter": "2024-01-15T00:00:00Z",
  "includeStatuses": ["ACCEPTED", "READY"]
}

​
Get Match History for a Date Range

{
  "scheduledAfter": "2024-01-01T00:00:00Z",
  "scheduledBefore": "2024-03-31T23:59:59Z",
  "includeStatuses": ["COMPLETED", "FORFEITED"],
  "limit": 100
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
identifier
string
required

Team ID or slug

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)