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

# Get Auto Top-up Settings

> Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `id` may be the authenticated account or an organization the caller belongs to.



## OpenAPI

````yaml api-reference/openapi/accounts.json GET /api/accounts/{id}/auto-top-up
openapi: 3.1.0
info:
  title: Recoup API - Accounts
  description: >-
    API documentation for the Recoup platform - an AI agent platform for the
    music industry
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/accounts/{id}/auto-top-up:
    get:
      description: >-
        Read the auto top-up settings for an account. Auto top-up is opt-in: it
        is off for every account until the account turns it on and chooses both
        the amount to buy and the balance that triggers it. When it is on, the
        api charges the default card on file for `amountCents` the first time a
        credit deduction leaves the balance below `thresholdCents`, then grants
        the credits and emails a receipt. `id` may be the authenticated account
        or an organization the caller belongs to.
      parameters:
        - name: id
          in: path
          description: >-
            The unique identifier (UUID) of the account. Must be the
            authenticated account or another accessible via organization
            membership.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Auto top-up settings (defaults when never configured).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpResponse'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpErrorResponse'
              example:
                error: Unauthorized
        '403':
          description: >-
            Forbidden - the account is not the caller's and not an organization
            they belong to (an unknown id also returns 403, never 404)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpErrorResponse'
      security:
        - apiKeyAuth: []
        - bearerAuth: []
components:
  schemas:
    AutoTopUpResponse:
      type: object
      required:
        - account_id
        - enabled
        - amountCents
        - thresholdCents
        - lastRunAt
        - lastError
      properties:
        account_id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        enabled:
          type: boolean
          description: Whether auto top-up is on. Off by default.
          example: true
        amountCents:
          type: integer
          nullable: true
          description: Amount charged and granted per top-up, in cents. Null until set.
          example: 10000
        thresholdCents:
          type: integer
          nullable: true
          description: Balance, in cents, below which a top-up runs. Null until set.
          example: 100
        lastRunAt:
          type: string
          format: date-time
          nullable: true
          description: When the last auto top-up was attempted. Null until the first run.
          example: '2026-09-04T15:05:00Z'
        lastError:
          type: string
          nullable: true
          description: >-
            Stripe decline message from the attempt that turned auto top-up off.
            Null while healthy or once re-enabled.
          example: Your card was declined.
    AutoTopUpErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: Add a payment method before turning on auto top-up
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Recoup API key. [Learn more](/quickstart#api-keys).
    bearerAuth:
      type: http
      scheme: bearer

````