Teams

Look up teams across all sports and leagues. Each row is one team within one league, with its current event count. Useful for building search/autocomplete, labelling odds rows, and understanding what’s currently active.

GET /api/v1/teams

AuthenticationPermalink for this section

Requires an API key. Available on all tiers (Free included). Unauthenticated requests return 401.

Query ParametersPermalink for this section

Example RequestsPermalink for this section

# Get all NBA teams
curl "https://api.sharpapi.io/api/v1/teams?league=nba" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Search for a team by name
curl "https://api.sharpapi.io/api/v1/teams?q=lakers" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Get all basketball teams
curl "https://api.sharpapi.io/api/v1/teams?sport=basketball" \
  -H "X-API-Key: YOUR_API_KEY"

// Search for a team
const response = await fetch(
  'https://api.sharpapi.io/api/v1/teams?q=arsenal',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } },
);
const { data, pagination } = await response.json();
 
console.log(`Found ${pagination.total} rows, showing ${pagination.count}`);
data.forEach(team => {
  console.log(`${team.name} (${team.sport}/${team.league}) - ${team.event_count} events`);
});

import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/teams',
    params={'sport': 'basketball', 'league': 'nba'},
    headers={'X-API-Key': 'YOUR_API_KEY'},
)
result = response.json()
 
print(f"Found {result['pagination']['total']} rows")
for team in result['data'][:10]:
    # numerical_id is omitted for teams with no atlas entry
    print(f"  {team['name']} [{team.get('numerical_id', '-')}] — {team['event_count']} events")

ResponsePermalink for this section

Success (200)Permalink for this section

Response to GET /api/v1/teams?q=arsenal&limit=3. Three rows, all named “Arsenal” or similar, each in a different league — and only the third has an atlas entry, so only it carries numerical_id, abbreviation and logo:

{
  "data": [
    {
      "name": "Arsenal (Stafford)",
      "sport": "soccer",
      "league": "cyber_live_arena_2x5_min",
      "event_count": 4
    },
    {
      "name": "Arsenal (V)",
      "sport": "soccer",
      "league": "soccer",
      "event_count": 3
    },
    {
      "name": "Arsenal",
      "numerical_id": 1308,
      "abbreviation": "ARS",
      "logo": "https://cdn.sharpapi.io/teams/soccer/1308.png",
      "sport": "soccer",
      "league": "england_-_premier_league",
      "event_count": 2
    }
  ],
  "pagination": {
    "limit": 3,
    "offset": 0,
    "count": 3,
    "total": 21,
    "has_more": true,
    "next_offset": 3,
    "next_cursor": "eyJ0IjoidGVhbXMiLCJ2IjoxLCJjIjoyLCJuIjoiQXJzZW5hbCIsInMiOiJzb2NjZXIiLCJsIjoiZW5nbGFuZF8tX3ByZW1pZXJfbGVhZ3VlIiwiaSI6MTMwOH0"
  },
  "updated_at": "2026-09-23T16:53:55.078830889Z"
}

A fully populated row — a US major-league team, where the atlas carries the metadata fields too:

{
  "name": "New York Yankees",
  "numerical_id": 20,
  "abbreviation": "NYY",
  "logo": "https://cdn.sharpapi.io/teams/baseball/20.png",
  "city": "New York",
  "mascot": "Yankees",
  "conference": "AL",
  "division": "East Division",
  "sport": "baseball",
  "league": "mlb",
  "event_count": 5
}

Team Object SchemaPermalink for this section

Row identity and numerical_idPermalink for this section

These are two different things, and they are easy to mix up.

Row identity — what makes a row unique in a response. A row is one team as it appears in one league, and the endpoint keys rows on the name + sport + league triple. That triple is what you should use as the primary key if you are storing the response as-is. Two rows can carry the same numerical_id (a team entered in several competitions), and rows with no atlas entry carry no numerical_id at all — so numerical_id alone cannot key a stored table.

numerical_id — the handle on the underlying atlas entry. It is the atlas entry this row resolved to. The integer itself is frozen and never reused, so it is the right thing to store when you want a key that survives a display-label change — that is what Entity reference IDs is about. Use it as the foreign key when joining /teams rows against odds rows and opportunity legs.

What it is not is a de-duplication key. Resolution happens per row, and one team entered in several leagues produces one row per league, all carrying the same value — Arsenal’s Premier League, EFL Cup and Champions League rows all carry 1308. Treat numerical_id as a join key, not as something that is unique within a response.

Odds rows and opportunity legs carry nested home / away blocks ({id, numerical_id, name, abbreviation, ...}) that resolve the two competitors inline, so you often don’t need to call this endpoint just to label a row. Those blocks are where the slug-style id appears. As with every nested reference block, treat them as optional — a block, or any field inside it, may be absent for an entity the atlas has not mapped. See Entity reference IDs for the full contract.

PaginationPermalink for this section

The response envelope is {data, pagination, updated_at} — the same flat shape as /events and /odds. There is no meta object on this endpoint.

Use CasesPermalink for this section

Team Name MappingPermalink for this section

Different sportsbooks use different names for the same team. The name on a /teams row is the normalized spelling — use it for display and for search-as-you-type, since q matches against it.

For storage and joins, prefer numerical_id: display labels can be retuned, and Entity reference IDs exists precisely so a label change doesn’t break your keys. Treat name as the thing you show a user, and numerical_id as the thing you store.

Search / AutocompletePermalink for this section

Use the q parameter to power a search-as-you-type UI:

curl "https://api.sharpapi.io/api/v1/teams?q=lak"

q is a plain case-insensitive substring match against the name field only — no other field is searched, so q=lak matches “Los Angeles Lakers” but q=LAL returns nothing.

Active TeamsPermalink for this section

Filter by event_count client-side to show only teams with current events.

Related EndpointsPermalink for this section

• Events - Get events for specific teams
• Leagues - List available leagues
• Sports - List available sports