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

# Get usage information

> Get current usage information for the authenticated API key.

Returns plan and organization details, rate-limit usage, and plan capabilities.



## OpenAPI

````yaml /openapi.json get /v1/usage
openapi: 3.1.0
info:
  title: PolyOrderbooks API
  description: >
    # PolyOrderbooks API


    Historical Polymarket **crypto** market data — discovery, prices, liquidity
    metrics, and L2 order books. Read paths query our historical data store;
    they never call Polymarket live.


    ## Base URL


    `https://api.polyorderbooks.com`


    ## Authentication


    All `/v1/*` data routes require an API key.


    Send `X-API-Key: pob_…` or `Authorization: Bearer pob_…`. Dashboard JWT
    session tokens are **not** accepted on data routes.


    ## Plans (hosted)


    | Plan | Req/min | Req/day | Finest resolution | History |

    | --- | --- | --- | --- | --- |

    | Starter | 60 | 1,000 | 60s | 7 days |

    | Pro | 300 | 50,000 | 1s | 31 days |

    | Scale | 1,000 | 200,000 | 1s | 90 days |


    ## Workflow


    1. `GET /v1/markets` — discover

    2. `GET /v1/markets/{id_or_slug}` — detail

    3. `GET /v1/markets/{id_or_slug}/books` — history
  version: 0.1.0
servers:
  - url: https://api.polyorderbooks.com
    description: Production
security: []
tags:
  - name: Discovery
    description: >-
      Discover series, events, and markets. Use returned ids or slugs in History
      endpoints.
  - name: History
    description: Historical metrics, prices, and L2 order book snapshots.
  - name: Utility
    description: Usage and account metadata.
paths:
  /v1/usage:
    get:
      tags:
        - Utility
      summary: Get usage information
      description: >-
        Get current usage information for the authenticated API key.


        Returns plan and organization details, rate-limit usage, and plan
        capabilities.
      operationId: get_usage_v1_usage_get
      responses:
        '200':
          description: Usage information including plan and limits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
              example:
                plan: starter
                organization: Acme Research
                limits:
                  requests_per_minute: 60
                  requests_remaining: 58
                  granularity_allowed: 60s
                  max_history_days: 7
                  data_points:
                    metrics: true
                    prices: true
                    books: true
                reset_at: 1754140860
        '401':
          description: API key is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing:
                  value:
                    detail: Authentication required.
                invalid:
                  value:
                    detail: Invalid API key.
        '429':
          description: Rate limit exceeded for the current API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Rate limit exceeded. Please try again later.
components:
  schemas:
    UsageResponse:
      properties:
        plan:
          type: string
          title: Plan
          description: Plan name for the current API key.
        organization:
          type: string
          title: Organization
          description: Organization name associated with the API key.
        limits:
          $ref: '#/components/schemas/UsageLimitsResponse'
          description: Rate-limit and plan capability information.
        reset_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Reset At
          description: >-
            Unix timestamp (seconds) when the rate-limit window resets. Null for
            unlimited plans.
      type: object
      title: UsageResponse
      description: Response body for `GET /usage`.
      example:
        limits:
          data_points:
            books: true
            metrics: true
            prices: true
          granularity_allowed: 60s
          max_history_days: 7
          requests_per_minute: 60
          requests_remaining: 58
        organization: Acme Research
        plan: starter
        reset_at: 1754140860
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable error description.
      type: object
      title: ErrorResponse
      description: Generic API error response.
    UsageLimitsResponse:
      properties:
        requests_per_minute:
          anyOf:
            - type: integer
            - type: string
          title: Requests Per Minute
          description: >-
            Plan rate limit in requests per minute, or `unlimited` for uncapped
            plans.
        requests_remaining:
          anyOf:
            - type: integer
            - type: string
          title: Requests Remaining
          description: Remaining requests in the current rate-limit window.
        granularity_allowed:
          type: string
          title: Granularity Allowed
          description: Finest historical resolution allowed by plan.
        max_history_days:
          anyOf:
            - type: integer
            - type: string
          title: Max History Days
          description: Maximum rolling lookback window in days, or `unlimited` if uncapped.
        data_points:
          $ref: '#/components/schemas/UsageDataPointsResponse'
          description: Data point categories available under the current plan.
      type: object
      title: UsageLimitsResponse
      description: Rate limit and granularity allowance for the current API key.
    UsageDataPointsResponse:
      properties:
        metrics:
          type: boolean
          title: Metrics
          description: Whether historical market metrics are allowed.
        prices:
          type: boolean
          title: Prices
          description: Whether historical prices are allowed.
        books:
          type: boolean
          title: Books
          description: Whether historical order books are allowed.
      type: object
      title: UsageDataPointsResponse
      description: Data point access controls for the current plan.

````