Credits System

Understand how credits work, what operations cost, and how to monitor your balance.

Overview

Credits are the unit of sale. 1 credit equals $1.00 of account balance. Your account holds a single balance, spendable on anything: articles, social posts, images, videos or research. There are no per-type pools and no separate "article credits". Each plan grants credits every billing cycle, and you can top up at any time. Credits are only consumed when you generate content: every read operation (GET request) is free.

Credit Costs

Operation	Credits	Endpoint	Notes
Article generation	1.5	`POST /api/v1/articles/generate`	Per article, regardless of word_count
Social media generation	0.6 per platform	`POST /api/v1/social/generate`	Multiplied by the number of platforms in the request
Publishing	0	`POST /api/v1/social/publish`	Publishing already-generated content is free
All read endpoints	0	Every `GET`	Lists, detail views, status polling, credits, usage

Social costs scale with the number of platforms in a single request. X plus LinkedIn costs 1.2 credits. All 10 supported platforms in one call costs 6 credits, and you still get back one content_id covering every variant.

Checking Your Balance

Use the GET /api/v1/user/credits endpoint to check your current credit balance at any time.

curl https://www.brainpercent.app/api/v1/user/credits \
  -H "Authorization: Bearer bp_your_key"

200Response

{
  "success": true,
  "data": {
    "available_credits": 42,
    "subscription_credits": 50,
    "purchased_credits": 0,
    "credits_used_this_month": 8,
    "plan": "Lite",
    "current_period_end": "2026-03-01T00:00:00Z"
  }
}

Where credits come from

Two sources, one balance. These fields tell you how the balance was funded, not where it can be spent: every credit buys the same actions at the same price.

Field	Description	Behavior
`subscription_credits`	Granted by your plan each billing period	Refreshed on renewal, spent first
`purchased_credits`	Top-ups bought in the dashboard	Never expire, spent after plan credits

available_credits is the number to check before generating. It is the whole balance, and it is what the API compares against when it decides whether to return a 402.

Handling Insufficient Credits

When you attempt an operation without enough credits, the API returns a 402 status code with the INSUFFICIENT_CREDITS error code.

402Response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "This operation requires 2.4 credits but your balance is 1.2"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T12:00:00Z"
  }
}

Do not retry a 402. Top up the balance, or reduce the number of platforms in the request, then send it again.

Pre-Check Pattern

Check the balance before a batch so you can fail gracefully instead of collecting 402s. The example below prices a social job: 0.6 credits per platform.

async function generateSocialWithCreditCheck(apiKey, sourceUrl, platforms, projectId) {
  const BASE = 'https://www.brainpercent.app/api/v1';

  // Check balance first
  const creditsRes = await fetch(`${BASE}/user/credits`, {
    headers: { 'Authorization': `Bearer ${apiKey}` },
  });
  const { data: credits } = await creditsRes.json();

  // 0.6 credits per platform.
  const cost = platforms.length * 0.6;

  if (credits.available_credits < cost) {
    console.error(`Insufficient credits: ${credits.available_credits} available, ${cost} required`);
    return null;
  }

  // Proceed with generation
  const res = await fetch(`${BASE}/social/generate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ source_url: sourceUrl, platforms, project_id: projectId }),
  });

  // The 202 body reports what was charged and what is left.
  const body = await res.json();
  console.log(`Charged ${body.data.credits_deducted}, remaining ${body.data.credits_remaining}`);
  return body;
}

Monitoring Usage

You can monitor your credit consumption in real time via the usage endpoint or the dashboard. For programmatic access, see the User API reference for full details on the usage and credits endpoints.