> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/sdk/javascript/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

> Use client.usage in the Reverse Contact TypeScript SDK to read workspace credits, API key limits and quota snapshots with a free authenticated request.

- Last verified: 2026-11-04

Read workspace credits and rate limits without spending credits.

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

Create `client` by following [Install and configure](https://docs.reversecontact.com/sdk/javascript/install). The `@reverse-contact/sdk` package exports `Body`, `Data`, `Query` and the other types used in the signatures.

JSON responses contain `data` and optional `quotas` and `metadata`. They also include the original `response`, with its body already read. See [First call](https://docs.reversecontact.com/sdk/javascript/first-call) for response handling.

HTTP errors use the [APIError subclasses and retry rules](https://docs.reversecontact.com/sdk/javascript/errors-and-retries): `BadRequestError`, `AuthenticationError`, `InsufficientCreditsError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `GoneError`, `UnprocessableEntityError`, `RateLimitError`, `DailyLimitError`, `KeyCreditLimitError`, `UnavailableForLegalReasonsError` and `InternalServerError`, according to the API response. Other statuses use `APIError`.

## retrieve()

Read balances and limits from `quotas`. The `data` field is `null`.

**Signature**

```typescript [TypeScript SDK]
client.usage.retrieve(
  options?: RequestOptions
): Promise<Result<Data<"getUsage">>>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `options` | `RequestOptions` | Optional per-request `timeout`, `maxRetries`, `headers` and `signal`. See [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). |

**Returns**

`Result<null>` with optional `quotas`, `metadata` and the HTTP `response`. Read `quotas.workspace.credits`, workspace limits and key limits. Quota snapshots and `quotas.key` can be `null`.

**Errors**

Calls can raise the HTTP `APIError` subclasses listed above. Network failures or cancellation raise `APIConnectionError`, and attempt timeouts raise `APITimeoutError`. `ReverseContactError` reports invalid SDK options or an invalid successful JSON response.

**Example**

**Example**

```typescript [TypeScript SDK]
const result = await client.usage.retrieve();
console.log(result.quotas?.workspace.credits.left);
console.log(result.quotas?.workspace.minuteRateLimit?.left);
```

## Related guides

[First call](https://docs.reversecontact.com/sdk/javascript/first-call), [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). Return to the [TypeScript SDK overview](https://docs.reversecontact.com/sdk/javascript).

## FAQ

### Does reading SDK usage cost credits?

`client.usage.retrieve()` calls the free Usage endpoint.

### Why is data null in a usage response?

Usage returns `data: null`. Workspace balances and rate limits are in the optional `quotas` field.

### Can usage quota snapshots be null?

Quota snapshot values and `quotas.key` can be `null`. Check for missing values before using a balance or limit as a number.