Crevio Usage API

openapi: 3.2.0
info:
  title: Crevio API V1 Usage API
  version: 1.0.0
  description: 'API for the Crevio creator platform — a multi-tenant SaaS for digital product sales.

    Uses snake_case keys following Stripe conventions. All resource IDs are string IDs (e.g., "prod_abc123").


    Authentication is a bearer token: `Authorization: Bearer $CREVIO_API_KEY`.

    List endpoints are cursor-paginated with `limit` and `starting_after`.

    Writes accept an `Idempotency-Key` header and are safe to retry.


    Every response carries IETF RateLimit headers (`RateLimit`, `RateLimit-Policy`) so a client can

    self-throttle, and `Retry-After` on a 429. The quota is 600 requests per minute per credential.


    The API is versioned in the URL path (`/v1`). Nothing is removed without in-band warning: a

    deprecated operation is marked `"deprecated": true` here and serves `Deprecation` (RFC 9745),

    `Sunset` (RFC 8594) and `Link; rel="deprecation"` headers for at least six months before it

    stops answering. See https://crevio.co/docs/developer/guides/versioning.'
  contact:
    email: support@crevio.co
    name: Crevio Support
    url: https://crevio.co/docs
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://crevio.co/legal/terms-of-service
servers:
- url: https://api.crevio.co/v1
  description: Production
security:
- ApiKey: []
tags:
- name: Usage
  description: Credit usage and transaction history
paths:
  /usage:
    get:
      summary: Get account usage
      description: Returns the authenticated account's credit balance (and how much of it comes from the plan, top-ups and bonuses), plan status and price, a forecast of whether the balance lasts until the billing cycle ends at the current spend rate, and credit spend for a window (the current billing cycle unless `start_time`/`end_time` say otherwise) broken down by operation, by day, and by the chats and scheduled tasks that spent the most.
      operationId: getUsage
      x-crevio-sdk-method: get
      tags:
      - Usage
      security:
      - ApiKey: []
      responses:
        '200':
          description: Account usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
      - name: period
        in: query
        required: false
        description: 'A named spend window in your time zone, instead of start_time and end_time (which it cannot be combined with): `cycle` (the current billing cycle, the default), `today`, `last_7_days` and `last_30_days` (each ending today), `this_month` or `last_month`.'
        schema:
          type: string
          enum:
          - cycle
          - today
          - last_7_days
          - last_30_days
          - this_month
          - last_month
      - name: start_time
        in: query
        required: false
        description: Start of the spend window, inclusive, as an ISO 8601 timestamp. Defaults to the start of the current billing cycle (the calendar month without a subscription).
        schema:
          type: string
          format: date-time
      - name: end_time
        in: query
        required: false
        description: End of the spend window, exclusive, as an ISO 8601 timestamp. Defaults to the end of the current billing cycle. The window cannot exceed 366 days. `credits`, `plan` and `forecast` always describe the current billing cycle.
        schema:
          type: string
          format: date-time
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.usage.get();\n\n  console.log(result);\n}\n\nrun();"
  /usage/transactions:
    get:
      summary: List usage transactions
      description: Returns the account's raw credit ledger (newest first), cursor-paginated. Spends are negative; grants are positive. Each entry may carry a `reference` to the resource that triggered the charge (currently generation jobs).
      operationId: listUsageTransactions
      x-crevio-sdk-method: transactions
      tags:
      - Usage
      security:
      - ApiKey: []
      parameters:
      - name: limit
        in: query
        required: false
        description: Number of transactions to return (1-100, default 15).
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: starting_after
        in: query
        required: false
        description: Transaction id (cred_…) to paginate forward from.
        schema:
          type: string
      - name: ending_before
        in: query
        required: false
        description: Transaction id (cred_…) to paginate backward from.
        schema:
          type: string
      - name: days
        in: query
        required: false
        description: Limit results to the last N days. Omit for full history.
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: List of usage transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_UsageTransaction'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.usage.transactions();\n\n  console.log(result);\n}\n\nrun();"
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: forbidden
              message: You do not have permission to perform this action
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: bad_request
              message: The request was malformed or contained invalid parameters
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: authentication_required
              message: You did not provide an API key.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    TooManyRequests:
      description: 'Rate limit exceeded — 600 requests per minute per owner on the free tier: every API key and OAuth token one person holds on an account shares one budget, and the account''s team keys share another. Retry after the number of seconds in `Retry-After`.'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: rate_limit_exceeded
              message: Too many requests. Please retry later.
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: api_error
              code: internal_error
              message: An unexpected error occurred
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
  schemas:
    UsageForecast:
      type: object
      properties:
        burn_rate_per_day:
          type: number
        runs_out_at:
          type:
          - string
          - 'null'
        projected_balance_at_period_end:
          type: number
        will_run_out:
          type: boolean
      required:
      - burn_rate_per_day
      - runs_out_at
      - projected_balance_at_period_end
      - will_run_out
    UsagePlan:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        status:
          type: string
        is_paid:
          type: boolean
        on_trial:
          type: boolean
        trial_ends_at:
          type:
          - string
          - 'null'
        renews_at:
          type:
          - string
          - 'null'
        price:
          type:
          - number
          - 'null'
        currency:
          type:
          - string
          - 'null'
        interval:
          type:
          - string
          - 'null'
        has_payment_method:
          type: boolean
      required:
      - name
      - status
      - is_paid
      - on_trial
      - trial_ends_at
      - renews_at
      - price
      - currency
      - interval
      - has_payment_method
    UsageCreditBalance:
      type: object
      properties:
        balance:
          type: number
        plan_credits:
          type: number
        top_up_credits:
          type: number
        bonus_credits:
          type: number
        monthly_allowance:
          type:
          - number
          - 'null'
        limit_reached:
          type: boolean
        auto_top_up:
          type: boolean
      required:
      - balance
      - plan_credits
      - top_up_credits
      - bonus_credits
      - monthly_allowance
      - limit_reached
      - auto_top_up
    UsageOperationSpend:
      type: object
      properties:
        operation:
          type: string
        description:
          type:
          - string
          - 'null'
        credits:
          type: number
      required:
      - operation
      - description
      - credits
    UsageTransaction:
      type: object
      properties:
        object:
          type: string
        id:
          type: string
        category:
          type: string
        operation:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        amount:
          type: number
        reference:
          type:
          - string
          - 'null'
        created_at:
          type: string
      required:
      - object
      - id
      - category
      - operation
      - description
      - amount
      - reference
      - created_at
    Usage:
      type: object
      properties:
        object:
          type: string
        plan:
          oneOf:
          - type: string
          - $ref: '#/components/schemas/UsagePlan'
          - type: 'null'
          description: ID by default, full object when expanded
        credits:
          oneOf:
          - type: string
          - $ref: '#/components/schemas/UsageCreditBalance'
          - type: 'null'
          description: ID by default, full object when expanded
        spend:
          oneOf:
          - type: string
          - $ref: '#/components/schemas/UsageSpend'
          - type: 'null'
          description: ID by default, full object when expanded
        forecast:
          oneOf:
          - type: string
          - $ref: '#/components/schemas/UsageForecast'
          - type: 'null'
          description: ID by default, full object when expanded
      required:
      - object
      - plan
      - credits
      - spend
      - forecast
    UsageSpend:
      type: object
      properties:
        period_start:
          type: string
        period_end:
          type: string
        time_zone:
          type: string
        total_credits:
          type: number
        today_credits:
          type: number
        by_operation:
          type: array
          items:
            $ref: '#/components/schemas/UsageOperationSpend'
        by_day:
          type: array
          items:
            $ref: '#/components/schemas/UsageDaySpend'
        by_chat:
          type: array
          items:
            $ref: '#/components/schemas/UsageChatSpend'
      required:
      - period_start
      - period_end
      - time_zone
      - total_credits
      - today_credits
      - by_operation
      - by_day
      - by_chat
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - api_error
              - invalid_request_error
              - validation_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
            errors:
              type: object
            doc_url:
              type: string
          required:
          - type
          - message
      required:
      - error
    ListResponse_UsageTransaction:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/UsageTransaction'
        has_more:
          type: boolean
        url:
          type: string
      required:
      - object
      - data
      - has_more
      - url
    UsageChatSpend:
      type: object
      properties:
        type:
          type: string
        id:
          type: string
        title:
          type:
          - string
          - 'null'
        credits:
          type: number
        runs:
          type:
          - number
          - 'null'
        last_charged_at:
          type: string
      required:
      - type
      - id
      - title
      - credits
      - runs
      - last_charged_at
    UsageDaySpend:
      type: object
      properties:
        date:
          type: string
        credits:
          type: number
      required:
      - date
      - credits
  headers:
    Sunset:
      description: Present only on a deprecated operation. HTTP-date (RFC 8594) after which the operation stops responding. Always at least six months after `Deprecation`.
      schema:
        type: string
        examples:
        - Thu, 01 Oct 2026 00:00:00 GMT
    RequestId:
      description: Unique id for this request. Quote it when reporting a problem.
      schema:
        type: string
        examples:
        - 8fe045fe-cb8a-4407-a44d-5df60385e522
    DeprecationLink:
      description: Present only on a deprecated operation. `<url>; rel="deprecation"` pointing at the migration notes.
      schema:
        type: string
        examples:
        - <https://crevio.co/docs/developer/guides/versioning>; rel="deprecation"
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        examples:
        - 11
    Deprecation:
      description: Present only on a deprecated operation. Structured-field date (RFC 9745) — `@` followed by the Unix timestamp at which the operation became deprecated.
      schema:
        type: string
        examples:
        - '@1775001600'
    RateLimit:
      description: 'Remaining quota for the current window, as an IETF structured field: `"default";r=<remaining>;t=<seconds until reset>`.'
      schema:
        type: string
        examples:
        - '"default";r=596;t=11'
    RateLimitPolicy:
      description: 'The quota this credential is subject to: `"default";q=<requests>;w=<window seconds>`.'
      schema:
        type: string
        examples:
        - '"default";q=600;w=60'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key in the format: Bearer {api_token}'
externalDocs:
  description: Crevio developer documentation
  url: https://crevio.co/docs/developer
x-mint:
  mcp:
    enabled: true
x-api-lifecycle:
  current_major_version: v1
  versioning_scheme: URL path
  deprecation_policy_url: https://crevio.co/docs/developer/guides/versioning
  minimum_notice_days: 183
  deprecation_headers:
  - Deprecation
  - Sunset
  - Link