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

# Get usage

> Check your effective plan, purchased credits, period usage, API-key quota, and remaining rate-limit capacity.

## Prerequisites

You need an [active API key](../authentication) and available rate-limit capacity. You do not need an available credit.

Read usage for the account that owns your API key. You do not supply query parameters or a request body.

This request consumes one rate-limit token but no credit. Your response reflects rate-limit capacity after this request's admission, and your usage is shared across all keys on the account.

## Response

You receive `200 OK` with this envelope:

<ResponseField name="success" type="boolean" required>
  Always `true` on success.
</ResponseField>

<ResponseField name="data" type="object" required>
  Your account's effective plan, balances, and usage.
</ResponseField>

### Account fields

| Field | Type | Meaning |
| - | - | - |
| `data.plan` | string | Your effective plan: `free` or `plus`. |
| `data.credits` | integer | Remaining purchased credits, separate from your included allowance. |
| `data.resetAt` | string | The next included-credit reset boundary, as an RFC 3339 UTC timestamp. |
| `data.rateLimit.limit` | integer | Rate-limit bucket capacity and refill rate in requests per minute. |
| `data.rateLimit.remaining` | integer | Whole tokens remaining after this request. |
| `data.period.start` | string | Start date of your quota period, in `YYYY-MM-DD` format. |
| `data.period.end` | string | Inclusive end-date label for the period, in `YYYY-MM-DD` format. For the exact reset instant, use `resetAt`. |

### Quotas

| Field | Type | Meaning |
| - | - | - |
| `data.quotas.requests.used` | integer | Credits consumed by admitted company searches and lookups during your current period. This includes purchased-credit consumption. |
| `data.quotas.requests.limit` | integer | Included credit allowance for your current period. |
| `data.quotas.requests.unit` | string | Always `"calls"`. |
| `data.quotas.apiKeys.used` | integer | Number of non-revoked API keys on your account. |
| `data.quotas.apiKeys.limit` | integer or null | API-key quota; `null` means unlimited. |
| `data.quotas.apiKeys.unit` | string | Always `"keys"`. |

To calculate your remaining included credits, subtract `quotas.requests.used` from `quotas.requests.limit` and clamp the result at zero. `used` can exceed `limit` when you have consumed purchased credits. For your available calls, add the remaining included credits to `credits`.

For a Plus subscription, your period can begin or end partway through a calendar day. Use `resetAt` rather than constructing a reset time from the date-only period labels.

## Errors

You can receive `401 unauthorized`, `429 rate-limit-exceeded`, or `500 authentication-failed`. An exhausted credit quota does not block this endpoint. See [Errors](../errors) and [Limits and credits](../limits).

<RequestExample>
  ```bash theme={null}
  curl --fail-with-body --silent --show-error \
    --header "Authorization: Bearer $NESU_API_KEY" \
    'https://api.nesu.pt/api/v1/usage'
  ```
</RequestExample>

<ResponseExample>
  Illustrative fixture response; your balances, dates, and remaining capacity will differ.

  ```json theme={null}
  {
    "success": true,
    "data": {
      "plan": "free",
      "credits": 250,
      "resetAt": "2026-10-01T00:00:00Z",
      "rateLimit": {
        "limit": 20,
        "remaining": 19
      },
      "period": {
        "start": "2026-09-01",
        "end": "2026-09-30"
      },
      "quotas": {
        "requests": {
          "used": 124,
          "limit": 500,
          "unit": "calls"
        },
        "apiKeys": {
          "used": 1,
          "limit": 2,
          "unit": "keys"
        }
      }
    }
  }
  ```
</ResponseExample>


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