> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polynode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Leaderboard Scopes

> Discover and search the categories or tags available to 1-day, 7-day, and 30-day realized-P&L leaderboards.

Use this endpoint to build category and tag navigation for rolling trader
leaderboards. It returns only scopes available for the selected period, ordered
by qualifying wallet count descending and then by name.

## Request

```text theme={null}
GET /v3/leaderboard/scopes
```

### Query parameters

| Parameter | Type    | Default  | Description                                                             |
| --------- | ------- | -------- | ----------------------------------------------------------------------- |
| `period`  | string  | required | `1d`, `7d`, or `30d`. Aliases `day`, `week`, and `month` are accepted.  |
| `scope`   | string  | required | `category` or `tag`. Plural aliases are accepted.                       |
| `q`       | string  | none     | Case-insensitive literal substring search. Up to 80 visible characters. |
| `limit`   | integer | 100      | Number of scopes. Values below 1 use 1; values above 200 use 200.       |
| `offset`  | integer | 0        | Pagination offset from 0 through 10,000.                                |

## Example

```bash theme={null}
curl "https://api.polynode.dev/v3/leaderboard/scopes?period=7d&scope=category&limit=3" \
  -H "x-api-key: $POLYNODE_API_KEY"
```

```json theme={null}
{
  "scopes": [
    {
      "value": "sports",
      "wallet_count": 7985,
      "ranked_count": 1000
    },
    {
      "value": "up-or-down",
      "wallet_count": 7634,
      "ranked_count": 1000
    },
    {
      "value": "esports",
      "wallet_count": 5496,
      "ranked_count": 1000
    }
  ],
  "count": 3,
  "total_count": 329,
  "limit": 3,
  "offset": 0,
  "has_more": true,
  "period": "7d",
  "scope": "category",
  "query": null
}
```

Counts change as new realized results enter the selected window.

## Response fields

| Field         | Type           | Description                                                       |
| ------------- | -------------- | ----------------------------------------------------------------- |
| `scopes`      | array          | Categories or tags in this page.                                  |
| `count`       | integer        | Number of scopes returned.                                        |
| `total_count` | integer        | Total scopes matching the selected period, type, and search text. |
| `limit`       | integer        | Effective page size.                                              |
| `offset`      | integer        | Effective pagination offset.                                      |
| `has_more`    | boolean        | Whether another reachable page exists.                            |
| `period`      | string         | Canonical period: `1d`, `7d`, or `30d`.                           |
| `scope`       | string         | Canonical scope type: `category` or `tag`.                        |
| `query`       | string or null | Normalized search text, or `null` when no search is active.       |

### Scope rows

| Field          | Type    | Description                                                                     |
| -------------- | ------- | ------------------------------------------------------------------------------- |
| `value`        | string  | Category or tag value accepted by the leaderboard.                              |
| `wallet_count` | integer | Wallets with qualifying realized results in the selected scope and period.      |
| `ranked_count` | integer | Ranks available through the corresponding rolling leaderboard, capped at 1,000. |

Use a returned `value` as `category` or `tags` on
[`GET /v3/leaderboard`](/data/leaderboard/global). Tag values also work as the
path slug on the [tag leaderboard](/data/leaderboard/tag-leaderboard).

## Errors

| Status | Error                     | When it occurs                                           |
| ------ | ------------------------- | -------------------------------------------------------- |
| `400`  | `invalid_period`          | `period` is missing or is not a rolling period.          |
| `400`  | `invalid_scope`           | `scope` is missing or is not `category` or `tag`.        |
| `400`  | `invalid_query`           | Search text is too long or contains a control character. |
| `400`  | `scope_offset_too_deep`   | `offset` is outside 0 through 10,000.                    |
| `401`  | authentication error      | The API key is missing or invalid.                       |
| `503`  | `leaderboard_unavailable` | Scope discovery is temporarily unavailable.              |


## OpenAPI

````yaml GET /v3/leaderboard/scopes
openapi: 3.1.0
info:
  title: PolyNode API
  description: >-
    Real-time Polymarket data API with decoded mempool settlements, OHLCV
    candles, and full Polygon JSON-RPC proxy.
  contact:
    name: PolyNode
    url: https://polynode.dev
  license:
    name: ''
  version: 2.0.0
servers:
  - url: https://api.polynode.dev
    description: Production
security:
  - api_key: []
paths:
  /v3/leaderboard/scopes:
    get:
      tags:
        - V3 Leaderboard
      summary: Discover rolling leaderboard scopes
      description: >-
        List or search categories and tags available to 1-day, 7-day, and 30-day
        realized-P&L leaderboards.
      operationId: v3_leaderboard_scopes
      parameters:
        - name: period
          in: query
          required: true
          schema:
            type: string
            enum:
              - 1d
              - 7d
              - 30d
          description: Rolling ranking window. Aliases day, week, and month are accepted.
        - name: scope
          in: query
          required: true
          schema:
            type: string
            enum:
              - category
              - tag
          description: Scope type. Plural aliases are accepted.
        - name: q
          in: query
          schema:
            type: string
            maxLength: 80
          description: Optional case-insensitive literal substring search.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 100
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
      responses:
        '200':
          description: Available categories or tags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3LeaderboardScopesResponse'
        '400':
          description: Invalid period, scope, search text, or offset
        '401':
          description: Unauthorized
        '503':
          description: Leaderboard scopes are temporarily unavailable
      security:
        - api_key: []
components:
  schemas:
    V3LeaderboardScopesResponse:
      type: object
      additionalProperties: false
      required:
        - scopes
        - count
        - total_count
        - limit
        - offset
        - has_more
        - period
        - scope
        - query
      properties:
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/V3LeaderboardScopeRow'
        count:
          type: integer
          minimum: 0
        total_count:
          type: integer
          minimum: 0
        limit:
          type: integer
          minimum: 1
          maximum: 200
        offset:
          type: integer
          minimum: 0
          maximum: 10000
        has_more:
          type: boolean
        period:
          type: string
          enum:
            - 1d
            - 7d
            - 30d
        scope:
          type: string
          enum:
            - category
            - tag
        query:
          type:
            - string
            - 'null'
    V3LeaderboardScopeRow:
      type: object
      additionalProperties: false
      required:
        - value
        - wallet_count
        - ranked_count
      properties:
        value:
          type: string
        wallet_count:
          type: integer
          minimum: 0
        ranked_count:
          type: integer
          minimum: 0
          maximum: 1000
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key

````