veezee-io Usage API

openapi: 3.2.0
info:
  title: Veezee Usage API
  version: '2.2'
  description: 'LinkedIn, Reddit, and X (Twitter) data for AI agents: profiles, companies, people search, posts, tweets, subreddits, and search, metered in credits with per-call receipts. Same contract as the MCP server at https://mcp.veezee.io/all.'
  contact:
    email: hello@veezee.io
    url: https://veezee.io
servers:
- url: https://api.veezee.io
security:
- bearerAuth: []
tags:
- name: Usage
paths:
  /v1/usage:
    get:
      operationId: getUsage
      summary: Check credits and recent charges
      description: Check your balance, plan, limits, and the last 10 charges (receipt ids included). Costs 0 credits and is exempt from the per-minute rate limit, so call it first to check your budget before running data tools, and any time after. Works the same on a trial key, a paid key, or an OAuth-connected account. The response includes upgrade_url (give it to your human when credits or plan limits block you; purchases credit this account directly with no login) and manage_url (give it to your human to change or cancel a paid plan in the Stripe billing portal). Trial accounts also get a claim_url that attaches an email so the account can be recovered if the key is lost. Not for fetching platform data.
      x-platform: null
      x-input-examples:
      - summary: Balance check
        value: {}
      parameters: []
      security:
      - bearerAuth: []
      responses:
        '200':
          description: usage envelope (schema_version 2)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usage_envelope'
        '400':
          description: INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '402':
          description: INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: NOT_ENTITLED | TRIAL_CAP_EXCEEDED
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: NOT_FOUND
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: IDEMPOTENCY_KEY_REUSED
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '413':
          description: PAYLOAD_TOO_LARGE
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: CONCURRENCY_LIMIT | RATE_LIMITED
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: INTERNAL
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: UPSTREAM_UNAVAILABLE
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: BUDGET_EXHAUSTED
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      tags:
      - Usage
components:
  schemas:
    Problem:
      type: object
      description: RFC 9457 problem details with Veezee extensions.
      properties:
        code:
          type: string
          enum:
          - INVALID_INPUT
          - NOT_FOUND
          - UNAUTHORIZED
          - NOT_ENTITLED
          - INSUFFICIENT_CREDITS
          - QUOTE_EXCEEDS_MAX_CREDITS
          - IDEMPOTENCY_KEY_REQUIRED
          - IDEMPOTENCY_KEY_REUSED
          - CONCURRENCY_LIMIT
          - RATE_LIMITED
          - TRIAL_CAP_EXCEEDED
          - BUDGET_EXHAUSTED
          - UPSTREAM_UNAVAILABLE
          - PAYLOAD_TOO_LARGE
          - INTERNAL
          - AUTH_REQUIRED
          - KEY_REQUIRED
        message:
          type: string
        param:
          type: string
        doc_url:
          type: string
        is_retriable:
          type: boolean
        retry_after_seconds:
          type: number
        valid_values:
          type: array
          items:
            type: string
        claim_url:
          type: string
        upgrade_url:
          type: string
          description: 'Present when a payment can fix this error. Give it to your human: it credits this key''s account directly with no login, and the same key keeps working after payment, nothing to reconfigure.'
        credits_required:
          type: number
          description: 'Set when the balance cannot cover the call''s quote: the credits the call needed.'
        offer:
          type: object
          description: Machine-readable purchase offer; present exactly when upgrade_url is. checkout_url is the same link as upgrade_url; resume says how to continue after payment.
          properties:
            offer_version:
              type: number
              const: 1
            reason:
              type: string
              enum:
              - INVALID_INPUT
              - NOT_FOUND
              - UNAUTHORIZED
              - NOT_ENTITLED
              - INSUFFICIENT_CREDITS
              - QUOTE_EXCEEDS_MAX_CREDITS
              - IDEMPOTENCY_KEY_REQUIRED
              - IDEMPOTENCY_KEY_REUSED
              - CONCURRENCY_LIMIT
              - RATE_LIMITED
              - TRIAL_CAP_EXCEEDED
              - BUDGET_EXHAUSTED
              - UPSTREAM_UNAVAILABLE
              - PAYLOAD_TOO_LARGE
              - INTERNAL
              - AUTH_REQUIRED
              - KEY_REQUIRED
            currency:
              type: string
              const: usd
            recommended:
              type: string
              enum:
              - flex
              - production
              description: Which pack to lead with.
            packs:
              type: array
              items:
                type: object
                properties:
                  pack:
                    type: string
                    enum:
                    - flex
                    - production
                  mode:
                    type: string
                    enum:
                    - payment
                    - subscription
                  price_usd_cents:
                    type: number
                  credits:
                    type: number
                  credits_per_month:
                    type: number
                  when:
                    type: string
                    description: Short label for when this pack fits.
                required:
                - pack
                - mode
                - price_usd_cents
            rails:
              type: array
              items:
                type: string
                enum:
                - stripe_checkout
            checkout_url:
              type: string
            resume:
              type: string
            refund_policy:
              type: string
          required:
          - offer_version
          - reason
          - currency
          - packs
          - rails
          - checkout_url
          - resume
          - refund_policy
      required:
      - code
      - message
      - doc_url
      - is_retriable
    usage_envelope:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        entity:
          type: string
          const: usage
        platform:
          anyOf:
          - type: string
            enum:
            - linkedin
            - reddit
            - x
          - type: 'null'
        canonical_url:
          anyOf:
          - type: string
          - type: 'null'
        data_as_of:
          anyOf:
          - type: string
          - type: 'null'
        schema_version:
          type: string
          const: '2'
        common:
          type: object
          properties:
            plan:
              type: string
              enum:
              - trial
              - payg
              - flex
              - production
            platforms:
              type: array
              items:
                type: string
              description: Platforms this account's key may call. Grants are explicit; write to hello@veezee.io to enable more.
            balance_remaining:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            free_tier:
              anyOf:
              - type: object
                properties:
                  credits_per_ip_day:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  used_today:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  remaining_today:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  resets:
                    type: string
                    description: UTC midnight when the day budget resets. ISO 8601.
                required:
                - credits_per_ip_day
                - used_today
                - remaining_today
                - resets
                additionalProperties: false
              - type: 'null'
              description: 'Present on trial keys: the shared per-IP day budget this key actually spends (balance_remaining stays 0 on the free tier; other callers on the same IP draw from the same pool). Null on paid plans.'
            realtime_ops_used:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            realtime_ops_limit:
              anyOf:
              - type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              - type: 'null'
              description: Null means unlimited (paid plans).
            concurrent_limit:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            recent_receipts:
              type: array
              items:
                type: object
                properties:
                  receipt_id:
                    type: string
                  tool:
                    type: string
                  credits_charged:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  created_at:
                    type: string
                required:
                - receipt_id
                - tool
                - credits_charged
                - created_at
                additionalProperties: false
              description: Up to the last 10 charges.
            claim_url:
              anyOf:
              - type: string
              - type: 'null'
              description: 'Present on trial accounts: open to attach an email so the account can be recovered if the key is lost.'
            upgrade_url:
              type: string
              description: Give this link to your human to add credits or upgrade; purchases credit THIS account with no login.
            manage_url:
              type: string
              description: Give this link to your human to change or cancel a paid plan in the Stripe billing portal. Valid at least 24 hours; call get_usage again for a fresh one.
          required:
          - plan
          - platforms
          - balance_remaining
          - free_tier
          - realtime_ops_used
          - realtime_ops_limit
          - concurrent_limit
          - recent_receipts
          - claim_url
          - upgrade_url
          - manage_url
          additionalProperties: false
        platform_fields:
          type: object
          properties: {}
          additionalProperties: false
        freshness:
          anyOf:
          - type: object
            properties:
              source_retrieved_at:
                anyOf:
                - type: string
                - type: 'null'
                description: When the data was fetched from the source. ISO 8601.
              served_at:
                type: string
              cache_age_seconds:
                anyOf:
                - type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                - type: 'null'
              served_from_cache:
                type: boolean
                description: True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are.
              freshness_requested:
                type: string
                enum:
                - recent
                - realtime
              freshness_served:
                type: string
                enum:
                - recent
                - realtime
                - stale
            required:
            - source_retrieved_at
            - served_at
            - cache_age_seconds
            - served_from_cache
            - freshness_requested
            - freshness_served
            additionalProperties: false
          - type: 'null'
        usage:
          type: object
          properties:
            receipt_id:
              anyOf:
              - type: string
              - type: 'null'
            credits_quoted:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            credits_charged:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            balance_remaining:
              anyOf:
              - type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              - type: 'null'
            free_tier_hint:
              description: 'Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key. Near the daily cap on unclaimed keys it also carries a claim link to relay to your human (claiming adds one-time credits).'
              type: string
          required:
          - receipt_id
          - credits_quoted
          - credits_charged
          - balance_remaining
          additionalProperties: false
      required:
      - entity
      - platform
      - canonical_url
      - data_as_of
      - schema_version
      - common
      - platform_fields
      - freshness
      - usage
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key, required on every call. Mint a free trial key instantly: POST https://api.veezee.io/v1/keys/mint (empty body, no signup, no card); trial keys carry the free per-IP daily budget. vz_live_... keys come from a purchase at https://veezee.io/upgrade; adding credits later upgrades the same key.'