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

# Usage

> Returns your plan, billing period, and credit usage, fetched live from
billing on every call. Any valid key may call this endpoint, whatever
routes it is granted, so it is also the safest way to test a key.

`credits.included` is the quota bundled into your plan; crossing it bills
overage rather than blocking. `credits.hard_cap` is where the gateway stops
serving with `402 limit_reached`. `usage_status` is a single field to
switch on.

**Cost:** free.




## OpenAPI

````yaml /openapi.yaml get /usage
openapi: 3.1.0
info:
  title: Eventory API
  version: '1.0'
  description: >
    Every HTTP endpoint of the Eventory platform, reached through the single
    public

    gateway at `https://api.eventory.ai`. The real-time notification stream is a

    WebSocket and is documented separately under **Real-time stream**.


    Authenticate every request with the `apikey` header. Each endpoint lists its

    credit cost; see **Credits & access** for how billing works.
  contact:
    name: Eventory
    url: https://eventory.ai
servers:
  - url: https://api.eventory.ai
    description: Production
security:
  - apiKey: []
tags:
  - name: Market Data
    description: |
      Historical and aggregated marketplace data for events and artists, plus
      full-text search over the Eventory catalog. Polling API.
      **1 credit per request** (sales list scales with rows requested).
  - name: Live Availability
    description: >
      On-demand scrape of the current ticket availability for one event on one
      of

      the eleven supported platforms. **5 credits per request.**
  - name: Watchlist
    description: |
      Manage the events your account monitors. The watchlist drives the
      real-time stream. **Free.**
  - name: Account
    description: Your plan and credit usage, live from billing. **Free.**
paths:
  /usage:
    get:
      tags:
        - Account
      summary: Usage
      description: >
        Returns your plan, billing period, and credit usage, fetched live from

        billing on every call. Any valid key may call this endpoint, whatever

        routes it is granted, so it is also the safest way to test a key.


        `credits.included` is the quota bundled into your plan; crossing it
        bills

        overage rather than blocking. `credits.hard_cap` is where the gateway
        stops

        serving with `402 limit_reached`. `usage_status` is a single field to

        switch on.


        **Cost:** free.
      operationId: getUsage
      responses:
        '200':
          description: Usage report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
              examples:
                active:
                  summary: Active subscription
                  value:
                    customer_id: cus_abc123
                    plan: basic
                    plan_ids:
                      subscription_id: sub_123
                      price_id: price_123
                      product_id: prod_123
                    status: active
                    usage_status: ok
                    cancel_at_period_end: false
                    canceled_at: null
                    trial_end: null
                    unit: credits
                    as_of: '2026-06-12T09:15:00Z'
                    period:
                      start: '2026-06-01T00:00:00Z'
                      end: '2026-07-01T00:00:00Z'
                      days_remaining: 19
                      elapsed_fraction: 0.3771
                    credits:
                      included: 5000
                      used: 1234
                      remaining: 3766
                      overage: 0
                      percent_used: 24.68
                      projected_used: 3272
                      hard_cap: 6000
                      in_overage: false
                none:
                  summary: No active subscription
                  value:
                    customer_id: cus_abc123
                    plan: null
                    plan_ids: null
                    status: none
                    usage_status: none
                    cancel_at_period_end: false
                    canceled_at: null
                    trial_end: null
                    unit: null
                    as_of: '2026-06-12T09:15:00Z'
                    period: null
                    credits:
                      included: 0
                      used: 0
                      remaining: 0
                      overage: 0
                      percent_used: 0
                      projected_used: null
                      hard_cap: 0
                      in_overage: false
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: >-
            Billing provider unreachable, or the plan is misconfigured. Retry
            with backoff; if `bad_plan_pricing` persists, contact support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailError'
              examples:
                stripe:
                  value:
                    detail: stripe_unavailable
                plan:
                  value:
                    detail: bad_plan_pricing
components:
  schemas:
    UsageResponse:
      type: object
      properties:
        customer_id:
          type: string
        plan:
          type:
            - string
            - 'null'
          description: Plan name. `null` without an active subscription.
        plan_ids:
          type:
            - object
            - 'null'
          properties:
            subscription_id:
              type: string
            price_id:
              type: string
            product_id:
              type: string
        status:
          type: string
          description: >-
            Subscription status. Only `active` and `trialing` are served by the
            gateway; `none` means no subscription.
          example: active
        usage_status:
          type: string
          enum:
            - ok
            - approaching_limit
            - over_included
            - at_hard_cap
            - none
          description: >-
            `approaching_limit` from 80% of `included`; `over_included` once
            overage starts; `at_hard_cap` when the gateway is refusing requests.
        cancel_at_period_end:
          type: boolean
        canceled_at:
          type:
            - string
            - 'null'
          format: date-time
        trial_end:
          type:
            - string
            - 'null'
          format: date-time
        unit:
          type:
            - string
            - 'null'
          description: Billing unit label
          usually `credits`.: null
        as_of:
          type: string
          format: date-time
        period:
          type:
            - object
            - 'null'
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
            days_remaining:
              type:
                - integer
                - 'null'
            elapsed_fraction:
              type:
                - number
                - 'null'
              description: 0 to 1.
        credits:
          type: object
          properties:
            included:
              type: integer
              description: Credits bundled into the plan for the period.
            used:
              type: integer
            remaining:
              type: integer
              description: Spendable credits left. Clamped to `hard_cap`.
            overage:
              type: integer
              description: Credits used beyond `included`.
            percent_used:
              type: number
            projected_used:
              type:
                - integer
                - 'null'
              description: >-
                End-of-period usage at the current pace. `null` at the very
                start of a period.
            hard_cap:
              description: Credits at which the gateway stops serving, or `"unlimited"`.
              oneOf:
                - type: integer
                - type: string
                  const: unlimited
            in_overage:
              type: boolean
    DetailError:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
    GatewayError:
      type: object
      description: >
        Envelope for every failure decided by the gateway (auth, ACL, billing,

        rate limit, unknown route, upstream 5xx). Key on `code`; `message` is
        prose

        and may change.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - unauthenticated
                - invalid_credentials
                - forbidden
                - no_subscription
                - limit_reached
                - no_billing_account
                - plan_unavailable
                - payment_required
                - invalid_parameter
                - rate_limited
                - not_found
                - service_unavailable
            message:
              type: string
  responses:
    Unauthenticated:
      description: No credential was sent, or the key was rejected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          examples:
            missing:
              value:
                error:
                  code: unauthenticated
                  message: Authentication is required to access this resource.
            invalid:
              value:
                error:
                  code: invalid_credentials
                  message: The provided credentials are invalid.
    RateLimited:
      description: More than 30 requests in the current minute. Back off.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: Your Eventory API key. Sent as the `apikey` request header.

````