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/v1/me

Get your account info

Returns the authenticated user, the API key being used (prefix only — full key is never disclosed), a quota summary, and how many swipe folders the key can see. Reach for it when you need to answer "which account is this key actually bound to?".

There is no plan field — subscription state lives in the Brandsearch app, which syncs the quota numbers here and nothing else.

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. Always true in practice: while an account is inactive, every request with its keys, this one included, is refused with 401 revoked_api_key.
Name
api_key.id
Type
string
Description
Identifies which of your API keys made the call. The key secret itself is never returned — we only ever store a one-way hash of it, so there is no last4 either.
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
true when 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. false for solo accounts.
Name
team_leader_external_user_id
Type
string
Description
When is_teammate is true, the external user ID of the team leader whose quota is being shared. null for solo accounts.
Name
role
Type
string
Description
owner or teammate.
Name
team_leader
Type
object
Description
{user_id, external_user_id, email, name} for the team leader. null unless this is a teammate key.
Name
folders
Type
object
Description
How many swipe folders this key can see, per type: {ads, brands, spectre}, each {owned, shared, total}. Counted exactly the way the folder listings count, so a disagreement with the dashboard is a real access problem rather than two ways of counting. null when unavailable — see folders_unavailable_reason.
Name
folders_unavailable_reason
Type
string
Description
Why folders is null: not_provisioned (the key's account is not linked to a Brandsearch user), account_link_broken (the account is linked to a Brandsearch user that no longer exists — your folders are not deleted, just unreachable; reconnecting the Brandsearch MCP connector or creating an API key in the dashboard repairs it), or users_db_unavailable. The endpoint still answers 200 in every case — identity has to work precisely when the rest does not.

Request

GET

/v1/me

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": {
    "id": "key_7c1e",
    "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,
  "role": "owner",
  "team_leader": null,
  "folders": {
    "ads": {"owned": 12, "shared": 3, "total": 15},
    "brands": {"owned": 4, "shared": 0, "total": 4},
    "spectre": {"owned": 2, "shared": 1, "total": 3}
  },
  "folders_unavailable_reason": null
}

GET/v1/usage

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_overrun is 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 credits charged today across all metered responses.
Name
credits_used_this_month
Type
integer
Description
Total credits 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
true when 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_used for 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: credits charged today by this teammate alone.
Name
your_credits_used_this_month
Type
integer
Description
For team accounts: credits charged this month by this teammate alone.

Request

GET

/v1/usage

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/v1/ai-credits

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
true once 90% or more of the pool is consumed.
Name
is_empty
Type
boolean
Description
true when nothing is left.
Name
is_teammate
Type
boolean
Description
true when 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

GET

/v1/ai-credits

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
}