User

Check your credit balance and monitor API usage.

Credits are the unit of account. 1 credit equals $1.00 of account balance, and your account holds one balance that every content type draws from. Article generation costs 1.5 credits, social generation costs 0.6 credits per platform.

GET/api/v1/user/credits

Returns your current credit balance, plan details, and billing period.

Request

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"
  }
}

GET/api/v1/user/usage

Returns API usage statistics including total requests, today's requests, rate limit info, and a 30-day daily breakdown.

Request

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

200Response

{
  "success": true,
  "data": {
    "total_requests": 1250,
    "today_requests": 42,
    "rate_limit": {
      "limit_per_minute": 1000,
      "remaining_per_minute": 958,
      "limit_per_day": 50000,
      "remaining_per_day": 49958,
      "reset": 1738368060
    },
    "daily_breakdown": [
      {
        "date": "2026-02-01",
        "endpoint": "/api/v1/articles",
        "total_requests": 25,
        "avg_response_time_ms": 120.5,
        "error_count": 0
      },
      {
        "date": "2026-02-01",
        "endpoint": "/api/v1/user/credits",
        "total_requests": 17,
        "avg_response_time_ms": 45.2,
        "error_count": 0
      }
    ]
  }
}

Credits Response Fields

Field	Type	Description
available_credits	integer	Your whole spendable balance (plan credits plus top-ups). This is the number to check before generating.
subscription_credits	integer	How much of the balance came from your plan. Refreshed each cycle and spent first.
purchased_credits	integer	How much of the same balance came from top-ups. Never expires and is spent after your plan credits. Not a second balance.
credits_used_this_month	integer	Credits consumed in the current billing period
plan	string	The billing record's plan name: Free, Lite, Professional, Business, Enterprise or Enterprise Custom. These are internal billing labels and do not always match the plan names on the pricing page, so treat this as a label to display, not a value to branch on.
current_period_end	datetime	When the current billing period ends (ISO 8601)

Daily Breakdown Format

The daily_breakdown array in the usage response contains per-day, per-endpoint statistics for the last 30 days:

Field	Type	Description
date	string	Date in YYYY-MM-DD format
endpoint	string	API endpoint path (e.g., /api/v1/articles)
total_requests	integer	Number of requests to this endpoint on this date
avg_response_time_ms	float	Average response time in milliseconds
error_count	integer	Number of error responses (4xx/5xx)

Rate Limit Object

The rate_limit object in the usage response provides current rate limit status:

Field	Type	Description
limit_per_minute	integer	Maximum requests allowed per minute
remaining_per_minute	integer	Requests remaining in current minute window
limit_per_day	integer	Maximum requests allowed per day. A value of -1 means unlimited.
remaining_per_day	integer	Requests remaining today
reset	integer	Unix timestamp when the per-minute window resets

Rate limits are applied per API key and depend on your plan:

Plan	Per minute	Per day
Free	100	5,000
Starter, Plus, Pro, Business	1,000	50,000
Enterprise	10,000	unlimited (-1)

Monitoring Automation

Combine the credits and usage endpoints to build monitoring automations:

• Low credit alerts: Poll GET /user/credits daily, alert when below threshold

• Usage dashboards: Aggregate daily_breakdown data for custom charts

• Rate limit monitoring: Check rate_limit.remaining_per_day before batch operations

• Error tracking: Monitor error_count in daily breakdowns for anomalies

See the Workflows guide and integration guides for complete monitoring automation examples.