> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/sdk/python/usage
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# client.usage

> Read Reverse Contact API credit balances and rate limits with client.usage.retrieve in Python, including request options, response fields and errors.

- Last verified: 2026-11-04

Read workspace credits, API key quotas and rate limits without spending credits.

| Method | Endpoint | Cost |
| ------ | -------- | ---- |
| [`retrieve()`](#retrieve) | [GET /v2/usage](https://docs.reversecontact.com/endpoints/usage) | Free. |

## Calling conventions

Examples assume `RC_API_KEY` is set. Signatures show the published 0.3.0 synchronous methods. Use the same arguments with the [Python async client](https://docs.reversecontact.com/sdk/python/async-client).

`models` refers to `reversecontact.types`. `NOT_GIVEN` and `NotGiven` are the SDK's internal markers for omitted arguments. Leave these arguments out of your calls. For API body parameters, passing `None` sends an explicit null. Transport options use `None` to inherit their defaults. `Timeout` means a number of seconds or `httpx.Timeout`. Supply parameters marked **Required** to Python or to the API, even when the generated signature permits omission.

JSON response objects expose `data`, `quotas`, `metadata` and `http_response`. Check optional fields for `None`. See [First call](https://docs.reversecontact.com/sdk/python/first-call) for the response envelope. CSV methods return text and iterators yield items.

HTTP failures raise an `APIError` subclass based on the response: `BadRequestError`, `AuthenticationError`, `InsufficientCreditsError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `GoneError`, `UnprocessableEntityError`, `RateLimitError`, `DailyLimitError`, `KeyCreditLimitError`, `UnavailableForLegalReasonsError` or `InternalServerError`. See the [error mapping and retry rules](https://docs.reversecontact.com/sdk/python/errors-and-retries).

## retrieve

Check your quotas with `client.usage.retrieve()`. See the [Usage endpoint](https://docs.reversecontact.com/endpoints/usage) for details.

**Python SDK**

```python [Python SDK]
def retrieve(
    *,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[None]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[None]`. `data` is `None`. Read `quotas` for credits and rate limits, and `metadata` for request diagnostics.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.usage.retrieve()
    if result.quotas and result.quotas.workspace and result.quotas.workspace.credits:
        print(result.quotas.workspace.credits.left)
```
## Related guides

See the [Python SDK overview](https://docs.reversecontact.com/sdk/python), [First call](https://docs.reversecontact.com/sdk/python/first-call) and [Client options](https://docs.reversecontact.com/sdk/python/client-options).

## FAQ

### Does checking usage cost credits?

`client.usage.retrieve()` returns account quotas and costs 0 credits.

### Why is data None in the Python usage response?

The Usage endpoint returns account information in `quotas`. That is why `client.usage.retrieve()` returns `data` as `None`.

### How do I read my remaining credits in Python?

Read `result.quotas.workspace.credits.left` after checking that `quotas`, `workspace` and `credits` are present.