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://recoup-api.vercel.app/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.

format: uuid

remaining_creditsintegerrequired

Credits still available in the current monthly period. Refills automatically once the period elapses.

minimum: 0

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.

minimum: 0

used_creditsintegerrequired

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

minimum: 0

is_probooleanrequired

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

timestampstringrequirednullable

ISO 8601 timestamp of the last balance update or monthly refill. Null when the account has never spent or refilled credits.

format: date-time

planstring · enumrequired

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

task_limitintegerrequirednullable

Enabled scheduled-task limit; null means unlimited.

min_cadence_minutesintegerrequired

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

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

401 example
{
  "error": "Unauthorized"
}

403Forbidden - account not accessible to the authenticated account

application/json

errorstringrequired

Human-readable error message.

Full specification

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

Download accounts.json
View operation source
json
{
  "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"
          }
        }
      }
    },
    "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"
          }
        }
      }
    }
  }
}