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

# GET /account/usage

> Monthly credit usage and remaining balance for the authenticated account.

## When to use it

Call it before a large `/batch` or `/crawl` to confirm you have enough balance,
or after a run to reconcile what was actually billed. Every field is scoped to
the account behind the `X-API-Key` you send — there is no account selector.

## Reading the numbers

`credits_used` is the sum of billed usage in the **current calendar month**.
It resets on the 1st.

`remaining_credits` is the live balance, **not** `monthly_credits - credits_used`.
Top-ups add to the balance without changing the monthly allowance, so the two
values diverge as soon as you buy extra credits.

`breakdown` groups the month's consumption by endpoint, so you can tell a
`/crawl` bill apart from a `/scrape` bill.

## Rate limit

30 requests per minute, per account. This endpoint is not meant for polling —
poll `GET /jobs/{job_id}` for job progress instead.

## Example

```bash cURL theme={null}
curl https://api.messora.dev/account/usage \
  -H "X-API-Key: YOUR_API_KEY"
```

## Related

The MCP `get_usage` tool returns the same data over the MCP protocol —
see [MCP integration](/en/mcp).


## OpenAPI

````yaml GET /account/usage
openapi: 3.1.0
info:
  description: >-
    ## Messora API


    Scraping com evasão anti-bot nativa. Retorna conteúdo limpo (Markdown / JSON
    estruturado / raw HTML).


    **Autenticação:** header `X-API-Key` em todas as rotas.


    **Créditos:** scrape markdown/raw = 1; JSON estruturado = 10; search = 1 por
    resultado; crawl = 1 por página bem-sucedida.
  summary: API de scraping LLM-ready com motor anti-bot nativo.
  title: Messora API
  version: 2.0.0
servers:
  - description: API pública do Messora
    url: https://api.messora.dev
security: []
paths:
  /account/usage:
    servers:
      - description: API pública do Messora
        url: https://api.messora.dev
    get:
      tags:
        - Uso
      summary: Retorna uso mensal de créditos da conta
      description: >-
        Retorna o consumo de créditos do mês corrente para a conta autenticada.
        O consumo vem de usage_records e o saldo disponível vem de
        accounts.balance.


        O campo `credits_used` é a soma de todos os scrapes bem-sucedidos do
        mês; `remaining_credits` inclui créditos de top-up.
      operationId: get_account_usage_account_usage_get
      responses:
        '200':
          content:
            application/json:
              example:
                breakdown:
                  - credits_used: 15
                    endpoint: /scrape
                  - credits_used: 8
                    endpoint: /batch
                credits_used: 23
                monthly_credits: 100
                plan: free
                remaining_credits: 77
              schema:
                $ref: '#/components/schemas/AccountUsageResponse'
          description: Uso mensal da conta
        '401':
          description: X-API-Key ausente
        '403':
          description: API key inválida ou revogada
        '429':
          description: Rate limit por tenant excedido (USAGE_RATE_LIMIT=30/min)
      security:
        - APIKeyHeader: []
components:
  schemas:
    AccountUsageResponse:
      description: Resposta de `GET /account/usage` (RF-010 / D-11).
      properties:
        breakdown:
          description: Consumo do mês agrupado por endpoint.
          items:
            $ref: '#/components/schemas/UsageBreakdownItem'
          title: Breakdown
          type: array
        credits_used:
          description: Soma dos créditos consumidos no mês-calendário corrente.
          title: Credits Used
          type: integer
        monthly_credits:
          description: Franquia mensal do plano.
          title: Monthly Credits
          type: integer
        plan:
          description: 'Plano da conta: free, starter, growth ou scale.'
          title: Plan
          type: string
        remaining_credits:
          description: >-
            Saldo disponível em accounts.balance. Inclui créditos de top-up, por
            isso não é necessariamente monthly_credits - credits_used.
          title: Remaining Credits
          type: integer
      required:
        - plan
        - monthly_credits
        - credits_used
        - remaining_credits
        - breakdown
      title: AccountUsageResponse
      type: object
    UsageBreakdownItem:
      description: Consumo de créditos agregado por endpoint no mês corrente.
      properties:
        credits_used:
          description: Créditos consumidos por essa rota no mês.
          title: Credits Used
          type: integer
        endpoint:
          description: Rota que consumiu créditos, como /scrape.
          title: Endpoint
          type: string
      required:
        - endpoint
        - credits_used
      title: UsageBreakdownItem
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey

````