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

# Current Plan Usage (Unlimited Plans)

> Check your unlimited plan's consumption: single lookups used against the monthly cap, bulk searches used against the daily limit, and when each resets.

Call this endpoint before submitting work, or to drive your own throttling. It reports both meters and their reset times:

| Meter                     | Fields                                                  | Resets                                                          |
| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------- |
| Monthly single-lookup cap | `single_monthly_cap`, `single_used`, `single_remaining` | At the end of the current billing period (`current_period_end`) |
| Daily bulk search limit   | `bulk_searches_per_day`, `bulk_searches_used_today`     | At the next UTC midnight (`bulk_searches_reset_at`)             |

The response also includes `single_rps` (your plan's per-account requests-per-second limit for single lookups) and the billing period bounds (`current_period_start`, `current_period_end`). All timestamps are ISO 8601 in UTC.

Calling this endpoint is free: it consumes neither the monthly cap nor the daily search limit. It does share the per-key request-rate window with the rest of the API, so avoid polling it in a tight loop.

The daily bulk search meter is per account, so its numbers include [dashboard bulk finder jobs run on your plan](/docs/guides/unlimited-plans#using-your-plan-in-the-dashboard), not just API submissions.

Requires an **Unlimited** API key with an active subscription; the same `402 subscription_inactive` and `403 wrong_key_plan` rules apply as on the other [unlimited endpoints](/docs/guides/unlimited-plans).


## OpenAPI

````yaml GET /v1/unlimited/usage
openapi: 3.1.0
info:
  title: OrbiSearch Public API
  version: 1.0.0
  description: >-
    Email verification API for developers and agents. [Get your API key
    →](https://orbisearch.com/dashboard/api-keys)


    **Rate limiting:** requests are limited per API key (20 requests per second
    by default). Every response includes `X-RateLimit-Limit`,
    `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describing the
    current per-key window so clients can self-throttle; `429` responses also
    include a `Retry-After` header with the suggested backoff in seconds.
  contact:
    name: Get API Key
    url: https://orbisearch.com/dashboard/api-keys
servers:
  - url: https://api.orbisearch.com
    description: OrbiSearch Public API
security:
  - ApiKeyAuth: []
paths:
  /v1/unlimited/usage:
    get:
      tags:
        - Unlimited Plans
      summary: Current Plan Usage
      description: |-
        Your plan's consumption for the current billing period: single-lookup
        requests used vs the monthly cap, bulk searches used today against the
        daily cap (with its next UTC-midnight reset time), and when the
        billing period resets. Free — does not count against the monthly cap
        (it does share the per-key request-rate window).
      operationId: unlimited_usage_v1_unlimited_usage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnlimitedUsageResponse'
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              example:
                detail: API key required in X-API-Key header
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '402':
          description: No active subscription for this key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                detail: >-
                  No active subscription. This key resumes working when the
                  subscription is reinstated.
                code: subscription_inactive
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '403':
          description: Key plan does not match this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                detail: >-
                  This endpoint requires an unlimited API key. Pay-as-you-go
                  keys use the credit-metered /v1 endpoints.
                code: wrong_key_plan
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: >-
                Seconds the client should wait before retrying. Computed from
                the remaining rate-limit window (typically 1 for the per-second
                limit, longer when the limit is exceeded by 3x or more); for
                endpoints with a daily quota, seconds until the quota resets.
              schema:
                type: integer
                examples:
                  - 1
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
          content:
            application/json:
              example:
                detail: >-
                  Rate limit exceeded. Maximum 20 requests per second per API
                  key. Contact us to discuss higher limits.
                code: rate_limited
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    UnlimitedUsageResponse:
      properties:
        single_monthly_cap:
          type: integer
          title: Single Monthly Cap
          description: Plan's single-lookup requests per billing period.
        single_used:
          type: integer
          title: Single Used
          description: Single-lookup requests consumed this billing period.
        single_remaining:
          type: integer
          title: Single Remaining
          description: Requests remaining before the monthly cap (never negative).
        single_rps:
          type: integer
          title: Single Rps
          description: Plan's single-lookup requests-per-second limit (per account).
        bulk_searches_per_day:
          type: integer
          title: Bulk Searches Per Day
          description: Plan's daily bulk search limit (per account, UTC day).
        bulk_searches_used_today:
          type: integer
          title: Bulk Searches Used Today
          description: Bulk searches consumed in the current daily window.
        bulk_searches_reset_at:
          type: string
          format: date-time
          title: Bulk Searches Reset At
          description: When the daily bulk search limit resets (next UTC midnight).
        current_period_start:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Current Period Start
          description: Start of the current billing period (cap window).
        current_period_end:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Current Period End
          description: End of the current billing period — when the cap resets.
      type: object
      required:
        - single_monthly_cap
        - single_used
        - single_remaining
        - single_rps
        - bulk_searches_per_day
        - bulk_searches_used_today
        - bulk_searches_reset_at
        - current_period_start
        - current_period_end
      title: UnlimitedUsageResponse
      description: Current-period consumption for an unlimited plan (/v1/unlimited/usage).
      example:
        bulk_searches_per_day: 10000
        bulk_searches_reset_at: '2026-07-29T00:00:00Z'
        bulk_searches_used_today: 2500
        current_period_end: '2026-08-01T00:00:00Z'
        current_period_start: '2026-07-01T00:00:00Z'
        single_monthly_cap: 100000
        single_remaining: 95789
        single_rps: 10
        single_used: 4211
    ApiErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable description of what went wrong.
          examples:
            - API key required in X-API-Key header
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Stable machine-readable error code, present on conditions a client
            may want to branch on (for example `rate_limited` for the per-second
            limit versus `daily_quota_exceeded` for the daily cap). Absent on
            errors that need no further disambiguation.
          examples:
            - daily_quota_exceeded
        errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/ValidationErrorDetail'
              type: array
            - type: 'null'
          title: Errors
          description: >-
            Individual validation failures, one entry per invalid parameter or
            field. Present only on 422 responses; when the request has a single
            problem, `detail` carries the same message. Absent on all other
            error codes.
      type: object
      required:
        - detail
      title: ApiErrorResponse
      description: Error response body.
    ValidationErrorDetail:
      properties:
        loc:
          type: string
          title: Loc
          description: >-
            Where in the request the problem is, as a dot-separated path (e.g.
            `query.email`, `body.0`).
          examples:
            - query.email
        msg:
          type: string
          title: Msg
          description: Human-readable description of this validation error.
          examples:
            - 'Missing required query parameter: email.'
        type:
          type: string
          title: Type
          description: >-
            Machine-readable error category (e.g. `missing`, `less_than_equal`,
            `string_too_long`).
          examples:
            - missing
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationErrorDetail
      description: One request-validation failure.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: API key for authentication
      in: header
      name: X-API-Key

````