Credits System

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

Overview

Credits are the currency for AI-powered operations in Brainpercent. Each plan includes a monthly credit allocation, and additional credits can be purchased. Credits are consumed when you generate content — read operations (GET requests) are always free.

Credit Costs

Operation	Credits	Endpoint	Notes
Article generation	40	`POST /api/v1/articles/generate`	Per article, regardless of length
Social media generation	9 per platform	`POST /api/v1/social/generate`	Multiplied by number of platforms
Video generation	25	Coming soon	-
Keywords research	8	Coming soon	-
Image generation	6	Coming soon	-

Social media costs scale with the number of platforms. Generating content for Twitter + LinkedIn costs 18 credits (9 x 2). Generating for all 4 platforms costs 36 credits (9 x 4).

Checking Your Balance

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

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

200Response

{
  "success": true,
  "data": {
    "available_credits": 850,
    "subscription_credits": 1000,
    "purchased_credits": 0,
    "credits_used_this_month": 150,
    "plan": "Pro",
    "current_period_end": "2026-03-01T00:00:00Z"
  }
}

Credit Types

Type	Description	Behavior
Subscription credits	Included with your plan each billing period	Reset monthly, do not roll over
Purchased credits	Bought separately via the dashboard	Never expire, used after subscription credits

When you consume credits, subscription credits are used first. Purchased credits are only consumed after subscription credits are exhausted.

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 40 credits but your balance is 12"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T12:00:00Z"
  }
}

Pre-Check Pattern

For expensive operations, it is a good practice to check your credit balance before making the request. This avoids unnecessary failures and lets you handle insufficient credits gracefully in your application.

async function generateWithCreditCheck(apiKey, topic, options = {}) {
  // Check balance first
  const creditsRes = await fetch('https://brainpercent.app/api/v1/user/credits', {
    headers: { 'Authorization': `Bearer ${apiKey}` },
  });
  const { data: credits } = await creditsRes.json();

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

  // Proceed with generation
  const res = await fetch('https://brainpercent.app/api/v1/articles/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ topic, ...options }),
  });

  return res.json();
}

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.