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

# Usage

> Shows your usage for each feature on your plan, such as customers, campaigns or media storage. For every feature, you see how much you've used, your limit and how much is left.

If a feature has no limit, `unlimited` is `true`, and `limit` and `remaining` are `null`.


## OpenAPI

````yaml /api-collection/chatflows-api-v1.json get /api/v1/usage
openapi: 3.1.0
info:
  title: ChatFlows REST API
  version: 1.0.0
  description: >-
    ChatFlows REST API (v1).


    **Base URL:** `https://app.chatflows.io/api/v1` — also shown, with a copy
    button, on your **Developer API Keys** page.


    **Auth:** every authenticated request sends `Authorization: Bearer <token>`,
    where the token is created under **Setup → Developer API Keys** in your
    dashboard.


    **What a token can see:** a token belongs to ONE workspace — your store's.
    Every endpoint returns only that workspace's data, and `/api/v1/account`
    describes your own workspace. A token created before tokens were tied to a
    workspace is refused with `401 token_not_scoped`; create a new one to
    replace it.


    **Scopes:** each endpoint's description lists the token ability it requires.
    Create your token with the matching scopes.


    **Pagination:** list endpoints return `{ data, links: { next, prev }, meta
    }`. Large/append-only collections (contacts, group members, webhooks) use
    opaque cursor pagination — follow `links.next` until it is `null`.
    `per_page` is clamped to 5–100.


    **Async sends:** message and OTP sends return `202` and are processed on the
    queue.


    **Error envelope:**

    ```json

    { "message": "...", "error_code": "...", "status": 4xx }

    ```


    **Modules:** Auth/Account · Channels · Contacts · Statuses · Sources ·
    Groups · Labels · Templates · Messages · Conversations · OTP.
servers:
  - url: https://app.chatflows.io
    description: ChatFlows
security:
  - bearerAuth: []
tags:
  - name: Root
    description: Unauthenticated service metadata.
  - name: Auth & Account
    description: Verify your token, and read workspace identity, plan and usage.
  - name: Channels
    description: Connected WhatsApp accounts and their phone numbers.
  - name: Customers
    description: Create, read, update, merge and bulk-manage customers.
  - name: Customer Statuses
    description: The pipeline statuses a contact can be assigned.
  - name: Customer Sources
    description: Where a contact originated (e.g. website, referral).
  - name: Customer Groups
    description: Named groups used to segment contacts and target campaigns.
  - name: Customer Labels
    description: Free-form labels for tagging contacts.
  - name: Templates
    description: WhatsApp message templates and their Meta approval status.
  - name: Messages
    description: Send template and free-form messages, and read delivery status.
  - name: Conversations
    description: Customer conversation threads and their message history.
  - name: OTP
    description: Send, verify and resend one-time passcodes over WhatsApp.
  - name: Error Examples
    description: Reference shapes for the errors any endpoint may return.
paths:
  /api/v1/usage:
    get:
      tags:
        - Auth & Account
      summary: Usage
      operationId: authAccountUsage
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: >-
                      Each feature on your plan, by name. The features depend on
                      your plan.
                    additionalProperties:
                      type: object
                      properties:
                        used:
                          type: integer
                          description: How much you've used.
                        limit:
                          type:
                            - integer
                            - 'null'
                          description: >-
                            Your plan's limit for this feature. `null` when
                            unlimited.
                        remaining:
                          type:
                            - integer
                            - 'null'
                          description: How much is left. `null` when unlimited.
                        unlimited:
                          type: boolean
                          description: '`true` if this feature has no limit.'
              examples:
                200 OK:
                  summary: 200 OK
                  value:
                    data:
                      api_requests:
                        used: 128
                        limit: 50000
                        remaining: 49872
                        unlimited: false
                      campaigns:
                        used: 6
                        limit: 10
                        remaining: 4
                        unlimited: false
                      contacts:
                        used: 1240
                        limit: 5000
                        remaining: 3760
                        unlimited: false
                      conversations:
                        used: 320
                        limit: null
                        remaining: null
                        unlimited: true
                      media_library_mb:
                        used: 150
                        limit: 1024
                        remaining: 874
                        unlimited: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/QuotaExhausted'
      security:
        - bearerAuth:
            - account:read
components:
  responses:
    Unauthorized:
      description: >-
        Missing, invalid or expired API token — or an older token that is not
        tied to a workspace (`token_not_scoped`), in which case create a new one
        on the Developer API Keys page.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Missing API token.
            error_code: unauthenticated
            status: 401
    PaymentRequired:
      description: >-
        Your workspace has no active subscription, or its first payment is still
        pending.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Subscription required or expired.
            error_code: subscription_required
            status: 402
    Forbidden:
      description: >-
        The token lacks the required scope, or the account is suspended or on
        hold.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: 'This token is missing the required scope: contacts:write.'
            error_code: insufficient_scope
            status: 403
    QuotaExhausted:
      description: The monthly API request quota for the workspace is exhausted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: API request quota exhausted for this billing period.
            error_code: quota_exhausted
            status: 429
      headers:
        RateLimit-Limit:
          schema:
            type: integer
          description: Your API request quota for the current billing period.
        RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining in the current billing period.
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until the quota resets.
  schemas:
    Error:
      type: object
      description: Standard error envelope returned by every endpoint.
      properties:
        message:
          type: string
          description: Human-readable explanation.
        error_code:
          type: string
          description: Stable machine-readable code — branch on this, not the message.
        status:
          type: integer
          description: HTTP status code.
      required:
        - message
        - error_code
        - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your API key. Create one under **Setup → Developer API Keys** and select
        the permissions this endpoint needs.

````

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