Account
These endpoints let you inspect who the API key belongs to, how much quota you have left, and how many AI credits remain. All of them are unmetered — they do not count against your quota or charge any credits.
Get your account info
Returns the authenticated user, the API key being used (prefix only — full key is never disclosed), and a quota summary.
The response also includes X-Quota-Charged: false so you can verify the request was not metered.
Response
- Name
user_id- Type
- string (UUID)
- Description
Your Brandsearch user ID. Stable across API key rotations.
- Name
external_user_id- Type
- string
- Description
Optional external user reference you can attach (e.g., your billing system's user ID).
- Name
email- Type
- string
- Description
Account email.
- Name
name- Type
- string
- Description
Account display name.
- Name
is_active- Type
- boolean
- Description
Whether the account is currently active.
- Name
api_key.prefix- Type
- string
- Description
First 12 characters of the API key (
bsk_xxxxxxxxx).
- Name
api_key.created_at- Type
- timestamp
- Description
When the API key was created.
- Name
api_key.last_used_at- Type
- timestamp
- Description
When the API key was last used (nullable).
- Name
quota.daily_limit- Type
- integer
- Description
Daily request limit.
- Name
quota.monthly_limit- Type
- integer
- Description
Monthly request limit.
- Name
quota.allow_overrun- Type
- boolean
- Description
Whether soft-overrun is allowed past the hard limit.
- Name
is_teammate- Type
- boolean
- Description
truewhen this account belongs to a team — quota ceilings (daily_limit,monthly_limit,allow_overrun) and active state are inherited from the team leader, and every teammate's requests draw from the same shared pool.falsefor solo accounts.
- Name
team_leader_external_user_id- Type
- string
- Description
When
is_teammateistrue, the external user ID of the team leader whose quota is being shared.nullfor solo accounts.
Request
curl https://api.brandsearch.co/v1/me \
-H "X-API-Key: bsk_your_api_key"
Response
{
"user_id": "8f4d8e9b-1b2c-4a5e-bb1a-1f5b3a9c2d4e",
"external_user_id": "stripe_cus_abc123",
"email": "founder@dtcbrand.co",
"name": "Jane Founder",
"is_active": true,
"api_key": {
"prefix": "bsk_a1b2c3d4",
"created_at": "2026-03-12T10:00:00Z",
"last_used_at": "2026-04-30T16:42:11Z"
},
"quota": {
"daily_limit": 10000,
"monthly_limit": 200000,
"allow_overrun": false
},
"is_teammate": false,
"team_leader_external_user_id": null
}
Get your current usage
Live quota counters for the authenticated user. Counters are shared across every API key the user owns. Use this to build dashboards, surface usage in your own product, or implement proactive throttling on your end.
Team accounts: when is_teammate is true, the limit / used / remaining counters reflect the shared team pool (every teammate draws from the same ceiling). The your_*_used fields show this individual teammate's contribution to that pool, useful for per-seat reporting. X-Quota-* response headers also reflect the shared pool.
Unmetered.
Response
- Name
daily_limit- Type
- integer
- Description
Total daily request quota.
- Name
daily_used- Type
- integer
- Description
Requests counted against today's quota.
- Name
daily_remaining- Type
- integer
- Description
max(0, daily_limit - daily_used).
- Name
monthly_limit- Type
- integer
- Description
Total monthly request quota.
- Name
monthly_used- Type
- integer
- Description
Requests counted against this month's quota.
- Name
monthly_remaining- Type
- integer
- Description
max(0, monthly_limit - monthly_used).
- Name
allow_overrun- Type
- boolean
- Description
Whether the account allows soft-overrun past the hard limit.
- Name
overrun_today- Type
- integer
- Description
Number of requests today that exceeded the daily limit (0 unless
allow_overrunis true).
- Name
overrun_this_month- Type
- integer
- Description
Number of requests this month that exceeded the monthly limit.
- Name
credits_used_today- Type
- integer
- Description
Total rows charged today across all metered responses.
- Name
credits_used_this_month- Type
- integer
- Description
Total rows charged this month.
- Name
last_reset_daily_at- Type
- timestamp
- Description
When the daily counter last reset (nullable).
- Name
last_reset_monthly_at- Type
- timestamp
- Description
When the monthly counter last reset (nullable).
- Name
is_teammate- Type
- boolean
- Description
truewhen this account is part of a team — limit/used/remaining counters reflect the shared team pool, not just this account.
- Name
your_daily_used- Type
- integer
- Description
For team accounts: this teammate's individual contribution to today's shared pool. Equal to
daily_usedfor solo accounts.
- Name
your_monthly_used- Type
- integer
- Description
For team accounts: this teammate's individual contribution to this month's shared pool.
- Name
your_credits_used_today- Type
- integer
- Description
For team accounts: rows charged today by this teammate alone.
- Name
your_credits_used_this_month- Type
- integer
- Description
For team accounts: rows charged this month by this teammate alone.
Request
curl https://api.brandsearch.co/v1/usage \
-H "X-API-Key: bsk_your_api_key"
Response
{
"daily_limit": 10000,
"daily_used": 1284,
"daily_remaining": 8716,
"monthly_limit": 200000,
"monthly_used": 38420,
"monthly_remaining": 161580,
"allow_overrun": false,
"overrun_today": 0,
"overrun_this_month": 0,
"credits_used_today": 24180,
"credits_used_this_month": 712340,
"last_reset_daily_at": "2026-04-30T00:00:00Z",
"last_reset_monthly_at": "2026-04-01T00:00:00Z",
"is_teammate": false,
"your_daily_used": 1284,
"your_monthly_used": 38420,
"your_credits_used_today": 24180,
"your_credits_used_this_month": 712340
}
Get your AI credit balance
Returns the account's AI-credit balance — the same shared, team-wide pool the Brandsearch dashboard spends on its AI features, read live so it always matches the gauge in the app.
AI credits are separate from your API request quota. They are spent by AI ad analysis (19 credits for a video creative, 14 for an image) and by the AI features in the dashboard.
Unmetered — this call counts 0 against your request quota and comes back with X-Quota-Charged: false.
Response
- Name
used- Type
- integer
- Description
AI credits consumed from the pool.
- Name
total- Type
- integer
- Description
Size of the pool.
- Name
remaining- Type
- integer
- Description
Credits left.
- Name
is_low- Type
- boolean
- Description
trueonce 90% or more of the pool is consumed.
- Name
is_empty- Type
- boolean
- Description
truewhen nothing is left.
- Name
is_teammate- Type
- boolean
- Description
truewhen this account is part of a team — in that case the numbers describe the team leader's pool, which every teammate draws from.
Errors
404 ai_credits_not_provisioned— the API key is not linked to a Brandsearch user, or that user has no AI-credit pool.503 service_unavailable— AI credits are not available on this deployment.
Request
curl https://api.brandsearch.co/v1/ai-credits \
-H "X-API-Key: bsk_your_api_key"
Response
{
"used": 419,
"total": 2000,
"remaining": 1581,
"is_low": false,
"is_empty": false,
"is_teammate": false
}