Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

Get account credits

On this page
GET/api/accounts/{id}/credits

Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the timestamp field reflects the last refill or balance update.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/accounts/YOUR_ID/credits' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request GET \
  --url 'https://api.recoupable.dev/api/accounts/{id}/credits'

Parameters

Path parameters

idstringrequired

The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.

Responses

200Credit balance retrieved successfully

application/json

account_idstringrequired

The unique identifier of the account this balance belongs to.

Example: "11111111-1111-4111-8111-111111111111"

format: uuid

remaining_creditsintegerrequired

Balance in integer micro-dollars. Can exceed the plan allowance after a top-up or be negative. This is a balance, not a lifetime-spend total.

Example: 292450000

total_creditsintegerrequired

Monthly refill floor in integer micro-dollars: Free 3,330,000; Starter 20,000,000; Pro 300,000,000. Top-ups can put remaining credits above this floor.

Example: 300000000

minimum: 0

used_creditsintegerrequired

max(0, total_credits - remaining_credits). A balance-derived display, not lifetime or period ledger spend.

Example: 7550000

minimum: 0

is_probooleanrequired

True when the account is on a pro plan, directly via an account subscription or via an organization subscription.

Example: true

timestampstring | nullrequired

ISO 8601 timestamp from the balance record; null when unavailable.

Example: "2026-10-01T12:00:00Z"

format: date-time

planstring · enumrequired

Values: "free", "starter", "pro"

Example: "pro"

task_limitinteger | nullrequired

Enabled scheduled-task limit; null means unlimited.

Example: null

min_cadence_minutesintegerrequired

Minimum allowed cadence: Free 10080, Starter 1440, Pro 60.

Example: 60

Free with an unavailable balance timestamp

free
{
  "account_id": "11111111-1111-4111-8111-111111111111",
  "remaining_credits": 3330000,
  "total_credits": 3330000,
  "used_credits": 0,
  "is_pro": false,
  "plan": "free",
  "task_limit": 1,
  "min_cadence_minutes": 10080,
  "timestamp": null
}

Paid Starter: is_pro remains false

starter
{
  "account_id": "11111111-1111-4111-8111-111111111111",
  "remaining_credits": 15000000,
  "total_credits": 20000000,
  "used_credits": 5000000,
  "is_pro": false,
  "plan": "starter",
  "task_limit": 3,
  "min_cadence_minutes": 1440,
  "timestamp": "2026-10-01T12:00:00Z"
}

Direct Pro

directPro
{
  "account_id": "11111111-1111-4111-8111-111111111111",
  "remaining_credits": 292450000,
  "total_credits": 300000000,
  "used_credits": 7550000,
  "is_pro": true,
  "plan": "pro",
  "task_limit": null,
  "min_cadence_minutes": 60,
  "timestamp": "2026-10-01T12:00:00Z"
}

Effective Pro through an organization

organizationPro
{
  "account_id": "11111111-1111-4111-8111-111111111111",
  "remaining_credits": 292450000,
  "total_credits": 300000000,
  "used_credits": 7550000,
  "is_pro": true,
  "plan": "pro",
  "task_limit": null,
  "min_cadence_minutes": 60,
  "timestamp": "2026-10-01T12:00:00Z"
}

Extra credits above the allowance: used_credits is zero

aboveAllotment
{
  "account_id": "11111111-1111-4111-8111-111111111111",
  "remaining_credits": 325000000,
  "total_credits": 300000000,
  "used_credits": 0,
  "is_pro": true,
  "plan": "pro",
  "task_limit": null,
  "min_cadence_minutes": 60,
  "timestamp": "2026-10-01T12:00:00Z"
}

Signed balance: usage display can exceed the allowance

negativeBalance
{
  "account_id": "11111111-1111-4111-8111-111111111111",
  "remaining_credits": -1000,
  "total_credits": 3330000,
  "used_credits": 3331000,
  "is_pro": false,
  "plan": "free",
  "task_limit": 1,
  "min_cadence_minutes": 10080,
  "timestamp": "2026-10-01T12:00:00Z"
}

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

401 example
{
  "error": "Unauthorized"
}

403Forbidden - account not accessible to the authenticated account

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json
View operation source
json
{
  "operationId": "getAccountsByIdCredits",
  "description": "Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the `timestamp` field reflects the last refill or balance update.",
  "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"
      }
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Credit balance retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountCreditsResponse"
          },
          "examples": {
            "free": {
              "summary": "Free with an unavailable balance timestamp",
              "value": {
                "account_id": "11111111-1111-4111-8111-111111111111",
                "remaining_credits": 3330000,
                "total_credits": 3330000,
                "used_credits": 0,
                "is_pro": false,
                "plan": "free",
                "task_limit": 1,
                "min_cadence_minutes": 10080,
                "timestamp": null
              }
            },
            "starter": {
              "summary": "Paid Starter: is_pro remains false",
              "value": {
                "account_id": "11111111-1111-4111-8111-111111111111",
                "remaining_credits": 15000000,
                "total_credits": 20000000,
                "used_credits": 5000000,
                "is_pro": false,
                "plan": "starter",
                "task_limit": 3,
                "min_cadence_minutes": 1440,
                "timestamp": "2026-10-01T12:00:00Z"
              }
            },
            "directPro": {
              "summary": "Direct Pro",
              "value": {
                "account_id": "11111111-1111-4111-8111-111111111111",
                "remaining_credits": 292450000,
                "total_credits": 300000000,
                "used_credits": 7550000,
                "is_pro": true,
                "plan": "pro",
                "task_limit": null,
                "min_cadence_minutes": 60,
                "timestamp": "2026-10-01T12:00:00Z"
              }
            },
            "organizationPro": {
              "summary": "Effective Pro through an organization",
              "value": {
                "account_id": "11111111-1111-4111-8111-111111111111",
                "remaining_credits": 292450000,
                "total_credits": 300000000,
                "used_credits": 7550000,
                "is_pro": true,
                "plan": "pro",
                "task_limit": null,
                "min_cadence_minutes": 60,
                "timestamp": "2026-10-01T12:00:00Z"
              }
            },
            "aboveAllotment": {
              "summary": "Extra credits above the allowance: used_credits is zero",
              "value": {
                "account_id": "11111111-1111-4111-8111-111111111111",
                "remaining_credits": 325000000,
                "total_credits": 300000000,
                "used_credits": 0,
                "is_pro": true,
                "plan": "pro",
                "task_limit": null,
                "min_cadence_minutes": 60,
                "timestamp": "2026-10-01T12:00:00Z"
              }
            },
            "negativeBalance": {
              "summary": "Signed balance: usage display can exceed the allowance",
              "value": {
                "account_id": "11111111-1111-4111-8111-111111111111",
                "remaining_credits": -1000,
                "total_credits": 3330000,
                "used_credits": 3331000,
                "is_pro": false,
                "plan": "free",
                "task_limit": 1,
                "min_cadence_minutes": 10080,
                "timestamp": "2026-10-01T12:00:00Z"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - invalid or missing authentication",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountCreditsErrorResponse"
          },
          "example": {
            "error": "Unauthorized"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - account not accessible to the authenticated account",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountCreditsErrorResponse"
          }
        }
      }
    }
  }
}