---
title: "Current usage"
method: GET
path: "/v1/usage"
tags: ["Workspace"]
---

# Current usage

`GET /v1/usage`

## Request

- Base URL: `https://api.mailbeast.ai`
- URL: `https://api.mailbeast.ai/v1/usage`
- Auth: HTTP bearer

Everything you have used and everything you have left, grouped by product: your Email Outreach plan limits and your Lead Finder credits. Check it before a large send or import. For billing cycles and renewal dates, see `GET /v1/account/subscription`.

Requires one of the following scopes: `usage:read`, `all:read`, `all:all`.

## Response `200`

- UsageResponseDto
  - `emailOutreach` EmailOutreachUsageDto, required
    - `planName` string, required: Your Email Outreach plan.
    - `limits` PlanUsageLimitDto[], required: The four Email Outreach plan limits.
      - `used` number, required: Units consumed this period.
      - `limit` number, nullable, required: The cap, or `null` when unlimited.
      - `remaining` number, nullable, required: Units left, or `null` when unlimited.
      - `isUnlimited` boolean, required
      - `usagePercentage` number, required: used / limit × 100 (0 when unlimited).
      - `limitType` 'monthly_emails' | 'active_contacts' | 'ai_credits' | 'email_validation', required
  - `leadFinder` LeadFinderUsageDto, required
    - `credits` LeadFinderCreditsDto, required
      - `used` number, required: Units consumed this period.
      - `limit` number, nullable, required: The cap, or `null` when unlimited.
      - `remaining` number, nullable, required: Units left, or `null` when unlimited.
      - `isUnlimited` boolean, required
      - `usagePercentage` number, required: used / limit × 100 (0 when unlimited).
      - `limitType` 'lead_finder_credits', required

## Other responses

- `401`: Missing or invalid API key.
- `403`: The key lacks a required scope, or the plan does not include API access.
- `429`: Rate limit exceeded - retry after the interval in the Retry-After header.

---

[API](https://skmtc.dev/mailbeast/apis/mailbeast-public-api.md) · [All operations](https://skmtc.dev/mailbeast/apis/mailbeast-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailbeast/apis/mailbeast-public-api/revisions/6440ce0738a4?raw)