API reference

Current User API

The /api/me endpoints let an authenticated client introspect itself — who it's connected as, which plan is active, what limits apply, and how much of those limits the current calendar month has already consumed. They're the first call every well-behaved integration should make.

AI agents check “do I still have search quota before issuing this query?”, dashboards surface plan status to end users, and debuggers settle “which key am I authenticated as right now?”.

Machine-readable spec: the always-current OpenAPI definition lives in the interactive Swagger UI and at /api/openapi.json.

Identity

Get current user, plan, and key info

Returns the authenticated user, their current plan with per-resource limits, the API key that authenticated the request (if any), and the effective dated API version. Use this as the first call in any integration to verify credentials and discover capabilities.

GET /api/me 
# who am I connected as, on which plan, with which key?
curl "https://www.audioscrape.com/api/me" \
     -H "Authorization: Bearer YOUR_API_KEY"
{
  "user": {
    "id": 42,
    "email": "[email protected]",
    "name": "Ada Lovelace",
    "member_since": "2024-09-12 14:03:11 UTC"
  },
  "plan": {
    "name": "pro",
    "limits": {
      "searches_per_month": 50000,
      "semantic_searches_per_month": 10000,
      "data_calls_per_month": 100000,
      "keyword_alerts": 25,
      "webhooks_enabled": true,
      "max_api_keys": 10,
      "transcription_minutes_per_month": 600,
      "storage_mb": 20480
    }
  },
  "api_key": {
    "id": 17,
    "key_name": "agent-orchestrator-prod",
    "pinned_version": "2026-02-01"
  },
  "api_version": "2026-02-01"
}

Response fields

Field Type Description
user object The authenticated user: id, email, name (nullable), member_since (ISO-8601 UTC timestamp of account creation, nullable).
plan object Current plan: name (slug — one of free, starter, basic, pro, enterprise) and a nested limits object (see below).
api_key object | null The API key the request was authenticated with: id, key_name, and pinned_version. null when authenticated via session cookie (e.g. a logged-in browser hitting the API).
api_version string Effective dated API version this request was evaluated against, per the Audioscrape-Version header / api_keys.pinned_version resolution.

Plan limits

Every field in plan.limits describes a per-resource cap. A null value means “unlimited”; a 0 on a quota field means the feature is disabled on this plan. For a side-by-side comparison of plans, see /pricing.

Field Type Description
searches_per_month integer | null Monthly text-search limit. null means unlimited.
semantic_searches_per_month integer | null Monthly semantic / hybrid search limit. null means unlimited; 0 means the feature is disabled on this plan.
data_calls_per_month integer | null Monthly data-API call limit (podcasts, episodes, persons, entities, charts, trending). null means unlimited; 0 means disabled.
keyword_alerts integer | null Maximum number of keyword alerts a user can create. null means unlimited.
webhooks_enabled boolean Whether webhook delivery is enabled for keyword alerts on this plan.
max_api_keys integer Maximum number of API keys the account can have active simultaneously.
transcription_minutes_per_month integer | null Monthly transcription quota for private uploads, in audio minutes. null means unlimited; 0 means uploads are disabled.
storage_mb integer | null Storage limit for private uploads, in megabytes. null means unlimited.
Quota

Get current usage and limits

Returns this calendar month's usage counters (searches, semantic searches, data calls, keyword alerts) alongside the plan's configured limits. Use it to handle 429 responses proactively — check usage before a heavy burst and back off if you're close to a cap.

GET /api/me/usage 
# how much of this month's quota is already gone?
curl "https://www.audioscrape.com/api/me/usage" \
     -H "Authorization: Bearer YOUR_API_KEY"
{
  "period": "2026-05",
  "searches": {
    "used": 1284,
    "limit": 50000
  },
  "semantic_searches": {
    "used": 312,
    "limit": 10000
  },
  "data_calls": {
    "used": 9417,
    "limit": 100000
  },
  "keyword_alerts": {
    "used": 4,
    "limit": 25
  }
}

Response fields

Field Type Description
period string Calendar month the usage counters cover (UTC, format YYYY-MM). Counters reset at the start of each month.
searches object Text-search usage. { used, limit } — see counter shape below.
semantic_searches object Semantic + hybrid search usage. Aggregates both action types into a single counter.
data_calls object Data-API call usage (podcasts, episodes, persons, entities, charts, trending).
keyword_alerts object Current count of keyword alerts the user has created vs the plan cap. Unlike the other counters this is a current-state total, not a per-period accumulator.

Counter shape

Each counter object has the same two fields:

Field Type Description
used integer Count used in the current period.
limit integer | null Configured plan limit for the period. null if unlimited.
Auth

Authentication

Both endpoints require a valid bearer token. API-key auth is the normal path for integrations and populates the api_key object in the response. A logged-in browser session also satisfies auth, in which case api_key is null. Missing or invalid credentials return 401 Unauthorized.

See Authentication for issuing keys, header conventions, and the Audioscrape-Version resolution rules.

Patterns

When to use it

Agent pre-flight quota check

Before issuing an expensive semantic search, an agent can confirm there's headroom and fall back to keyword search (or defer the call) when close to the cap: 

import requests

H = {"Authorization": f"Bearer {API_KEY}"}
usage = requests.get("https://www.audioscrape.com/api/me/usage", headers=H).json()

sem = usage["semantic_searches"]
if sem["limit"] is not None and sem["used"] >= sem["limit"] * 0.95:
    # Within 5% of the cap — fall back to cheaper text search.
    search_type = "text"
else:
    search_type = "semantic"

Connection sanity check

Surface the active identity and plan in a dashboard, CLI banner, or MCP server's startup logs so users know which credentials are in play: 

curl -sf "https://www.audioscrape.com/api/me" \
     -H "Authorization: Bearer $AUDIOSCRAPE_API_KEY" \
| jq -r '"Connected as \(.user.email) on \(.plan.name) plan (key: \(.api_key.key_name // "session"))"'

Tip: both endpoints are cheap, but /api/me is effectively static within a billing period — cache it for the lifetime of your process. /api/me/usage is dynamic; refresh it on demand or at a low cadence (e.g. once per minute) when building real-time quota displays.

Previous
Upload Audio
Next
MCP Overview