Skip to main content
POST
/
orgs
/
{identifier}
/
matches
curl -X POST https://teambattles.gg/api/v1/orgs/Esports_Org/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"leagueTeamsOnly": true, "excludeStatuses": ["CANCELLED"], "limit": 50}'

{
  "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/orgs/Esports_Org/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"leagueTeamsOnly": true, "excludeStatuses": ["CANCELLED"], "limit": 50}'

​
Permission Required

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

​
Membership Required

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

​
Organization Identifier

The {identifier} path parameter accepts either:
  • Organization ID: The Convex document ID (e.g., kd8xyz789ghi012)
  • Organization Slug: The URL-friendly org name (e.g., Esports_Org)
The slug is derived from the organization name by replacing spaces with underscores.

​
What’s Returned

This endpoint returns matches for all teams within the organization. This is useful for organization admins or dashboards that need to see activity across all teams.

​
Filtering Options

​
League Teams Only

The leagueTeamsOnly parameter is unique to this endpoint:
ParameterTypeDescription
leagueTeamsOnlybooleanOnly include matches involving LEAGUE type teams
LEAGUE teams are teams created for organized league play, as opposed to regular competitive teams.

​
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 All League Matches

{
  "leagueTeamsOnly": true,
  "limit": 50
}

​
Get Active Matches Across All Teams

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

​
Get Completed League Matches for Stats

{
  "leagueTeamsOnly": true,
  "includeStatuses": ["COMPLETED", "FORFEITED"],
  "limit": 100
}

​
Get Matches for a Specific Game

{
  "gameId": "call_of_duty_bo7",
  "excludeStatuses": ["CANCELLED"]
}

​
Get Organization Match History for a Season

{
  "scheduledAfter": "2024-01-01T00:00:00Z",
  "scheduledBefore": "2024-06-30T23:59:59Z",
  "leagueTeamsOnly": true,
  "includeStatuses": ["COMPLETED"],
  "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

Organization ID or slug

Body

application/json

Optional filters and pagination options. Includes additional leagueTeamsOnly filter specific to organization queries.

​
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

​
leagueTeamsOnly
boolean

Only include matches involving LEAGUE type teams

Response

Successful response

​
matches
object[]
​
count
integer

Number of matches returned in this page

​
pagination
object
​
timestamp
string<date-time>

Response timestamp (ISO 8601)