Compass DocsBy Mesa
Open App

👤 Identity (GET /v1/me)

Returns the account, plan, live credit balance, and pricing behind the API key you authenticate with. Use it to confirm a key works and to read your balance before you spend. It is free.

Request

GET /v1/me
Base URL https://api.compass.mesa.so
Auth Authorization: Bearer ck_live_…
Scope read:metadata
Cost 0 credits (free)
Version every response carries Compass-API-Version (currently 1.4.0) 
curl https://api.compass.mesa.so/v1/me \
  -H "Authorization: Bearer ck_live_your_key_here"

Response 200

{
  "apiVersion": "1.4.0",
  "baseUrl": "https://api.compass.mesa.so",
  "docs": "https://compass.mesa.so/docs/api",
  "endpoints": [
    { "method": "GET", "path": "/v1/me", "summary": "Your identity, plan, credit balance, and this endpoint list. Always free.", "credits": 0 },
    { "method": "GET", "path": "/v1/people", "summary": "Search and filter people. Supports q, roles, channels, contactType, sort.", "credits": 5 }
    // ...every other endpoint, each with its own credit price
  ],
  "id": "clx0...",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "tier": "starter",
  "sampleMode": false,
  "organization": "Example Labs",
  "creditsBalance": 2850,
  "apiKey": {
    "label": "agent",
    "prefix": "ck_live_AbCdEf",
    "scopes": ["read:metadata", "read:contacts"],
    "environment": "live"
  },
  "pricing": {
    "currency": "credits",
    "basicCallCredits": 5,
    "privateCallCredits": 10,
    "note": "Data calls cost 5 credits. Revealing a contact's private channels costs 10 credits the first time (a permanent unlock); later calls on that contact cost 5. Credits come from your plan, referrals, or a top-up."
  },
  "meta": {
    "creditsCharged": 0,
    "creditsBalance": 2850
  }
}

Fields

Field Type Description
apiVersion string The API build you are talking to. Also sent as the Compass-API-Version header.
baseUrl string Where to send every other call. Read it from here rather than hard-coding a host.
docs string Where to read more.
endpoints array Every endpoint with its method, path, summary and credits. Generated from the same price table that bills you, so the quote and the charge cannot disagree.
id string The account the key belongs to.
name string The account holder's name.
email string The account holder's email.
tier string The plan: free, starter, pro, team, or enterprise.
sampleMode boolean true when this key is being served the free sample plane instead of live data. Balance is the gate, not the plan: it is true only while you are on free AND hold fewer credits than a call costs. Add credits and it goes false with no plan change.
organization string The workspace name, or Compass if none is set.
creditsBalance number Credits available right now. Data calls cost 5; a private reveal costs 10.
apiKey.label string The label you gave the key.
apiKey.prefix string The key's display prefix, such as ck_live_AbCdEf.
apiKey.scopes string[] What the key may read: read:metadata and read:contacts.
apiKey.environment string The key's environment, such as live.
pricing object The credit cost of a basic call (basicCallCredits) and a private reveal (privateCallCredits).
meta.creditsCharged number Credits this call charged (0 for /v1/me).
meta.creditsBalance number Your balance after this call. /v1/me charges nothing, so it repeats creditsBalance above.

Errors

Code Reason
401 The key is missing, malformed, or revoked.
429 You hit the rate limit. Back off and retry.

Data calls (not /v1/me) can also return 402 when you are out of credits. See Errors & Status Codes.