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

# Retrieve your usage

> The calling key's calls this month, its quota and rate limit.

The calling key's calls this month, its monthly quota and rate limit, and what the key is.

| Field | Meaning |
| - | - |
| `period` | The current month, `YYYY-MM`, in UTC |
| `calls.data`, `calls.analytics` | Counted calls this month, per product |
| `monthly_quota` | Calls allowed per month across all products, or `null` for no quota |
| `rate_limit_per_minute` | Calls allowed per UTC minute |
| `key.name` | The key's name in the customer portal |
| `key.mode` | `live` or `test` |
| `key.products` | The products the key may call: `data`, `analytics` |

A usage call is counted like any other call. [Rate limits & usage](https://docs.pinakelai.com/guides/rate-limits-and-usage.md) explains how calls are counted.

```bash cURL theme={null}
curl "https://api.pinakelai.com/v1/usage" \
  -H "Authorization: Bearer $PINAKEL_API_KEY"
```

```python Python theme={null}
import os

import requests

resp = requests.get(
    "https://api.pinakelai.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['PINAKEL_API_KEY']}"},
    timeout=30,
)
resp.raise_for_status()
usage = resp.json()
```

```javascript JavaScript theme={null}
const res = await fetch("https://api.pinakelai.com/v1/usage", {
  headers: { Authorization: `Bearer ${process.env.PINAKEL_API_KEY}` },
});
const usage = await res.json();
```

```json 200 theme={null}
{
  "period": "2026-12",
  "calls": {
    "data": 4180,
    "analytics": 0
  },
  "monthly_quota": 100000,
  "rate_limit_per_minute": 600,
  "key": {
    "name": "Docketing sync (production)",
    "mode": "live",
    "products": ["data"]
  }
}
```

```json 401 theme={null}
{
  "type": "https://docs.pinakelai.com/errors/unauthenticated",
  "title": "Authentication required",
  "status": 401,
  "detail": "Send the API key as Authorization: Bearer <key>, not as X-API-Key.",
  "request_id": "req_01M7Q41K1M2N3P4Q5R6S7T8V9W"
}
```


## OpenAPI

````yaml GET /v1/usage
openapi: 3.1.0
info:
  title: Pinakel Trademark Data API
  summary: 'Trademark records from 119 registers: search, retrieve, sync and coverage.'
  description: >
    Structured trademark records from national, regional and international
    registers, normalized into one object.


    - **Authentication:** every endpoint except `GET /v1/health` needs
    `Authorization: Bearer <key>` (`pk_live_...` or `pk_test_...`). Keys are
    never accepted in the URL.

    - **Errors** are RFC 9457 problem details (`application/problem+json`) whose
    `type` links to the error's documentation; every response carries
    `X-Request-Id`.

    - **Limits:** the `RateLimit` and `RateLimit-Policy` headers report the
    key's per-minute and monthly allowance; `429` responses say which one ran
    out and when to retry.

    - **Pagination** is by opaque cursor: send `next_cursor` back with the same
    filters.

    - **Stability:** v1 only gains additive changes. Enumerations in responses
    are open (`x-extensible-enum`): treat unknown values as `other`.


    Guides, concepts and coverage: https://docs.pinakelai.com
  termsOfService: https://www.pinakelai.com/terms-of-use
  contact:
    name: Pinakel API support
    url: https://docs.pinakelai.com/
  license:
    name: 'Proprietary: use under the Pinakel terms of use'
    url: https://www.pinakelai.com/terms-of-use
  version: 1.0.0
servers:
  - url: https://api.pinakelai.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Trademarks
    description: Search, retrieve and batch-retrieve records.
  - name: Changes
    description: Follow every record that changed, by cursor.
  - name: Jurisdictions
    description: Registers covered, their state and freshness.
  - name: Account
    description: Your usage, and the public health check.
paths:
  /v1/usage:
    get:
      tags:
        - Account
      summary: Retrieve your usage
      description: >-
        Calls billed to the presented key this UTC month, per product, with its
        quota and rate limit. This call counts like any other.
      operationId: retrieveUsage
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          description: invalid-request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '401':
          description: unauthenticated, key-revoked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: product-not-enabled
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '429':
          description: rate-limited, quota-exceeded
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: internal-error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '503':
          description: unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        default:
          description: Any other problem (RFC 9457).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
components:
  schemas:
    Usage:
      properties:
        period:
          type: string
          title: Period
          description: The UTC month counted, YYYY-MM.
        calls:
          $ref: '#/components/schemas/UsageCalls'
        monthly_quota:
          anyOf:
            - type: integer
            - type: 'null'
          title: Monthly Quota
          description: Calls per month across products; null = no quota.
        rate_limit_per_minute:
          type: integer
          title: Rate Limit Per Minute
        key:
          $ref: '#/components/schemas/UsageKey'
      type: object
      required:
        - period
        - calls
        - monthly_quota
        - rate_limit_per_minute
        - key
      title: Usage
    ProblemDocument:
      properties:
        type:
          type: string
          title: Type
        title:
          type: string
          title: Title
        status:
          type: integer
          title: Status
        detail:
          type: string
          title: Detail
        request_id:
          type: string
          title: Request Id
        errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/FieldErrorDocument'
              type: array
            - type: 'null'
          title: Errors
        violated_policies:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Violated Policies
      additionalProperties: true
      type: object
      required:
        - type
        - title
        - status
        - detail
        - request_id
      title: ProblemDocument
      description: OpenAPI schema of every error response (RFC 9457).
    UsageCalls:
      properties:
        data:
          type: integer
          title: Data
          description: Billed data API calls this month.
        analytics:
          type: integer
          title: Analytics
          description: Billed Analytics API calls this month.
      type: object
      required:
        - data
        - analytics
      title: UsageCalls
    UsageKey:
      properties:
        name:
          type: string
          title: Name
        mode:
          type: string
          title: Mode
          x-extensible-enum:
            - live
            - test
        products:
          items:
            type: string
          type: array
          title: Products
      type: object
      required:
        - name
        - mode
        - products
      title: UsageKey
    FieldErrorDocument:
      properties:
        code:
          type: string
          title: Code
        detail:
          type: string
          title: Detail
        parameter:
          anyOf:
            - type: string
            - type: 'null'
          title: Parameter
        pointer:
          anyOf:
            - type: string
            - type: 'null'
          title: Pointer
      additionalProperties: false
      type: object
      required:
        - code
        - detail
      title: FieldErrorDocument
      description: OpenAPI schema of one `errors[]` item.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key: Authorization: Bearer pk_live_... (or pk_test_...).'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.