Account (me)

The me endpoints describe the calling user, account, plan, features, usage and account-wide spend history. Credit fields are additive; existing USD values have not been renamed or reinterpreted.

Endpoints

GET /v1/me

curl -X GET "https://example.com/v1/me"

{
  "status": "info",
  "data": {
    "account_id": "acc_01HZ456",
    "created_at": 1717200000,
    "email": "person@example.com",
    "id": "user_01HZ123",
    "members": [
      {
        "email": "person@example.com",
        "name": "Person Surname",
        "type": "member",
        "user_id": "user_01HZ123"
      },
      {
        "email": "newhire@example.com",
        "type": "invitation"
      }
    ],
    "name": "Person Surname",
    "plan": {
      "features": {
        "api_access": true,
        "audience_research": true,
        "csv_export": true,
        "custom_date_filter": true,
        "daily_digest": true,
        "digest_webhook": true,
        "mcp": true,
        "multisource_research": true,
        "webhooks": true
      },
      "limits": {
        "max_research_depth": 1000,
        "num_seats": 5,
        "parallelism": 5,
        "projects": -1,
        "tracking_agents": -1
      },
      "name": "Business",
      "type": "subscription"
    },
    "team_name": "Acme",
    "teams": [
      {
        "account_id": "acc_01HZ456",
        "name": "Acme"
      }
    ],
    "usage": {
      "balance_total": 450,
      "balance_used": 12.34,
      "billing": {
        "catalog_version": "2026-09-15",
        "credit_rate_usd": "0.007000",
        "precision": 6,
        "unit": "credits"
      },
      "credits_total": "64285.714286",
      "credits_used": "1762.857143",
      "renews_at": 1790812800
    }
  }
}

GET /v1/me/usage_history

curl -X GET "https://example.com/v1/me/usage_history"

{
  "status": "info",
  "data": [
    {
      "billing_catalog_version": "2026-09-15",
      "category": "mention",
      "created_at": 1717200000,
      "credit_rate_usd": "0.015000",
      "credit_value_basis": "snapshot",
      "id": 9183271,
      "quantity": 0.5,
      "quantity_credits": "33.333333"
    }
  ],
  "has_next": true,
  "cursor": "string"
}

{
  "status": "info",
  "error_code": "invalid_cursor",
  "detail": "string",
  "transient": true
}

Current account and usage

• Identity: id, account_id, email, name, team_name, created_at.
• members[]: joined members and pending invitations.
• teams[]: other accounts the caller belongs to.
• plan: name, type, features and limits. Read returned capability flags rather than inferring access from a display name.
• plan.type: billing kind — subscription, one_time or one_time_renewable, not a commercial-tier slug. Unknown types do not imply higher-tier access; use returned features and limits.
• plan.limits.num_seats: invited teammate capacity, excluding the owner. Pro V2 and V3 include one invited teammate; Business includes five. Existing over-cap members remain, but no further invitations can be added while the account is at or above its capacity.
• usage: credits_used, credits_total, billing, balance_used, balance_total, renews_at. There is no public usage.balance or usage.currency field.

Example usage block inside the success envelope's data:

{
  "credits_used": "100.000000",
  "credits_total": "11933.333333",
  "billing": {
    "unit": "credits",
    "credit_rate_usd": "0.015000",
    "catalog_version": "2026-09-15",
    "precision": 6
  },
  "balance_used": 1.5,
  "balance_total": 179,
  "renews_at": 1790812800
}

Credit totals are six-decimal strings derived from actual consumed and granted USD at the current account rate, not a fixed advertised plan allocation. billing.unit selects credits or USD presentation. balance_used and balance_total remain numeric USD. renews_at is Unix seconds or null. If current contract credit terms are unavailable, credits_used, credits_total and billing are null; USD usage remains readable.

Usage history

GET /v1/me/usage_history returns a cursor-paginated, account-wide spend-only feed in the usual success envelope. Each row contains id, category, quantity and created_at, plus additive credit metadata. quantity is non-negative numeric USD charged, not credits or a signed refund amount. Rows have no endpoint field.

Example item inside data:

{
  "id": 9183271,
  "category": "mention",
  "quantity_credits": "100.000000",
  "credit_rate_usd": "0.020000",
  "billing_catalog_version": "2026-09-15",
  "credit_value_basis": "snapshot",
  "quantity": 2,
  "created_at": 1789552800
}

With credit_value_basis: "snapshot", complete captured event quantity and rate remain unchanged after a plan change, including without a current rate. The example's event rate can differ from today's usage rate.

Pre-snapshot history falls back to the current rate and explicitly says credit_value_basis: "current". If no current rate exists, all four credit metadata fields are null. Do not call a current-rate fallback an event-time snapshot or sum differently rated snapshots to rebuild the current wallet.

Data categories include mention, audience_profile, post_processing and preview_generation. AI usage can appear as ai_assistant; other in-app categories may also appear. Treat unknown strings defensively. Current POST /v1/ask and MCP Ask incur token-based inference charges; the old static assistant action is not a fixed fee on current turns.

Next steps

• Pricing — data weights and AI inference.
• GET /v1/prices — credit prices and USD values.