Partner API: Billing & Usage

Access to the Partner API is arranged directly with your Exlitem account contact — there's no public signup and no card on file. Usage is metered per request and invoiced monthly based on actual calls made that period.

#What's Billable

The contact-reveal surcharge is a flat, non-negotiable add-on — not part of your account's regular per-unit pricing — charged only on calls where a real email or phone value is actually returned, never merely for holding the contact_info capability. See Search & Profile Endpoints for how contact info is gated.

• Only successful (2xx) responses are billed. Errors and rate-limited requests cost nothing.
• Idempotent retries: send an Idempotency-Key header (any unique string ≤ 128 chars). Retries with the same key within 24 hours return the same result and are billed once.
• Every billable response includes:

X-Exlitem-Units-Charged: 1

#Monthly Caps

If your account has an agreed monthly call ceiling, exceeding it returns 402 PAYMENT_REQUIRED (error.detail.reason: "monthly_cap_reached") for the rest of the billing period. Most accounts have no such ceiling.

There is no purchasable "balance" to monitor for standard accounts — you aren't billed per top-up, you're invoiced for what you used.

#Tracking Your Usage

GET /usage is free and reports your usage for the current billing period:

GET /partner/v1/usage
Authorization: Bearer exl_partner_live_...

{
  "success": true,
  "data": {
    "billing_period": "2026-07",
    "billing_model": "postpaid_invoice",
    "balance_remaining": null,
    "monthly_hard_cap_units": null,
    "period_usage": {
      "search": 1210,
      "profile_view": 340,
      "similar": 55,
      "total_units": 1605
    },
    "daily_breakdown": [
      { "date": "2026-07-06", "search": 402, "profile_view": 118, "similar": 12 },
      { "date": "2026-07-07", "search": 380, "profile_view": 97, "similar": 20 }
    ],
    "rate_limit_per_min": 60,
    "daily_call_limit": 5000
  },
  "pagination": null,
  "error": null
}

Standard accounts are billed monthly by usage, so balance_remaining is null — it only appears non-null for the rare account still on the legacy prepaid model. monthly_hard_cap_units is your agreed monthly call ceiling, if your account has one.

#Reducing Your Bill

• Cache responses on your side. Profile data and search results don't change minute-to-minute — caching for up to 24 hours (matching the Idempotency-Key window) avoids re-billing the same view.
• Page deliberately. Each page of GET /search is a separate billable call — request the page size you need rather than over-fetching.
• Use free endpoints for lookups. GET /filters and GET /disciplines are free and cacheable for 10 minutes — use them to populate filter UIs instead of guessing valid values.

#Next Steps

Continue to Errors, Rate Limits & Integration Checklist to finish preparing for production traffic.