Skip to main content
POST
/
leagues
/
{identifier}
/
penalties
curl -X POST https://teambattles.gg/api/v1/leagues/my-league/penalties \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "all", "limit": 50}'

{
  "penalties": [
    {}
  ],
  "cooldowns": [
    {}
  ],
  "count": 123,
  "timestamp": "2023-11-07T05:31:56Z"
}
curl -X POST https://teambattles.gg/api/v1/leagues/my-league/penalties \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "all", "limit": 50}'

​
Permission Required

This endpoint requires the leagues.league_admin permission on your API key.

​
Membership Required

You must have a MANAGER or higher role in the league, or be a TeamBattles staff member, to access league penalties. If you lack the required access, you’ll receive a 403 error.

​
League Identifier

The {identifier} path parameter accepts the league slug - the URL-friendly league name (e.g., my-league).

​
What’s Returned

Returns penalties and/or cooldowns for a specific league. The response always includes both penalties and cooldowns arrays - use the type parameter to control which data is fetched.
This is an admin endpoint. Unlike the public endpoints (discover, profile, standings, seasons, rules), this endpoint requires the leagues.league_admin permission and MANAGER+ league role.

​
Request Body

ParameterTypeRequiredDescription
typestringNoData type to fetch: penalties, cooldowns, or all (default)
teamIdstringNoFilter penalties by a specific team ID
gameIdstringNoFilter penalties by a specific game ID
limitnumberNoMaximum results to return (1-100, default 50)

​
Type Parameter

ValueDescription
penaltiesReturns only point penalties
cooldownsReturns only match cooldowns
allReturns both penalties and cooldowns (default)

​
Filtering Options

​
Team Filtering

Use teamId to filter penalties for a specific team.

​
Game Filtering

Use gameId to filter penalties related to a specific game.
The teamId and gameId filters only apply to penalties, not cooldowns.

​
Common Use Cases

​
Get All Penalties and Cooldowns

{
	"type": "all",
	"limit": 50
}

​
Get Penalties Only

{
	"type": "penalties",
	"limit": 100
}

​
Get Penalties for a Specific Team

{
	"type": "penalties",
	"teamId": "jh7abc123def456",
	"limit": 25
}

​
Get Active Cooldowns Only

{
	"type": "cooldowns"
}

​
Get Penalties for a Specific Game

{
	"type": "penalties",
	"gameId": "call_of_duty",
	"limit": 50
}

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

League slug

Body

application/json

Optional type, team, game filters, and limit

​
type
enum<string>
default:all

Data type to fetch: penalties, cooldowns, or all

Available options:
penalties,
cooldowns,
all
​
teamId
string

Filter penalties by a specific team ID

​
gameId
string

Filter penalties by a specific game ID

​
limit
integer
default:50

Maximum number of results to return (1-100)

Required range: 1 <= x <= 100

Response

Successful response

​
penalties
object[]
​
cooldowns
object[]
​
count
integer

Total count of penalties and cooldowns returned

​
timestamp
string<date-time>

Response timestamp (ISO 8601)