Get Organization 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"], "numItems": 50}'

{
  "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>"
}

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

{
  "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>"
}

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

Parameter	Type	Description
`leagueTeamsOnly`	boolean	Only 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).

Request Fields

Parameter	Type	Description
`numItems`	number	Number of items per page, 1-100, default 25
`cursor`	string	Opaque cursor string from a prior response (optional)

Response Fields

Field	Type	Description
`page`	array	Array of matches for this page
`isDone`	boolean	`true` when there are no more pages to fetch
`continueCursor`	string	Pass back as `cursor` on the next request

Example response envelope:

{
	"page": [],
	"isDone": false,
	"continueCursor": "eyJpZCI6Im1hdGNoXzEyMyIsInRzIjoxNzA0MDY3MjAwfQ=="
}

Errors

Code	HTTP Status	When
`error_api_key_required`	401	Missing `Authorization` header
`error_api_key_invalid`	401	API key is unknown, revoked, or expired
`error_api_key_permission_denied`	403	The key does not hold `matches.org_matches: read`
`error_org_membership_required`	403	You are not an active member of the requested organization
`error_invalid_num_items`	400	`numItems` is outside the allowed `1-100` range
`error_invalid_limit`	400	Reserved for `limit`-style page sizes (registry-level error code)
`error_invalid_cursor`	400	`cursor` is malformed or no longer valid
`error_invalid_date_format`	400	One of the `scheduled`/`created` filters is not ISO 8601
`error_org_not_found`	404	The `{identifier}` could not be resolved to an organization
`error_team_not_found`	404	`opponentId` could not be resolved to a team
`error_internal`	500	Unhandled server error - retry or contact support

Common Use Cases

Get All League Matches

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

Get Active Matches Across All Teams

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

Get Completed League Matches for Stats

{
	"leagueTeamsOnly": true,
	"includeStatuses": ["COMPLETED", "FORFEITED"],
	"numItems": 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"],
	"numItems": 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)

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)

leagueTeamsOnly

boolean

Only include matches involving LEAGUE type teams

Response

Successful response

page

object[]

required

Show child attributes

isDone

boolean

required

continueCursor

string

required

Get Team Matches Get Global Badges

Documentation Index

​Permission Required

​Membership Required

​Organization Identifier

​What’s Returned

​Filtering Options

​League Teams Only

​Status Filtering

​Date Filtering

​Other Filters

​Pagination

​Request Fields

​Response Fields

​Errors

​Common Use Cases

​Get All League Matches

​Get Active Matches Across All Teams

​Get Completed League Matches for Stats

​Get Matches for a Specific Game

​Get Organization Match History for a Season

Authorizations

Path Parameters

Body

Response

Permission Required

Membership Required

Organization Identifier

What’s Returned

Filtering Options

League Teams Only

Status Filtering

Date Filtering

Other Filters

Pagination

Request Fields

Response Fields

Errors

Common Use Cases

Get All League Matches

Get Active Matches Across All Teams

Get Completed League Matches for Stats

Get Matches for a Specific Game

Get Organization Match History for a Season