> ## Documentation Index > Fetch the complete documentation index at: https://docs.intentleads.si/llms.txt > Use this file to discover all available pages before exploring further. # Get usage (same as balance) > Same as `GET /api/v1/billing/balance`, kept for older clients. **Free.** This doesn't spend your balance. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/usage openapi: 3.1.0 info: title: Intent Leads API version: '1.0' description: >- The Intent Leads API finds B2B people actively researching the topics you sell into, and exports them with contact details into your own tools. **Authentication.** Send an API key as a bearer token: `Authorization: Bearer il_live_…`. Standard keys work with everything except billing, team and key management, which need an admin key. **Organizations and workspaces.** An organization holds the balance, invoices and people; lanes, leads, exports, lists, websites and webhooks live in its workspaces. A workspace key works in its workspace. An organization key manages workspaces, billing and people, and works in any of its workspaces with the header `Intent-Leads-Workspace: `. **What costs money.** Only `POST /api/v1/exports` with `"dry_run": false` spends your [balance](/guides/billing) (and website visitors as they're identified). Quotes, counts, checks, estimates, samples and re-downloads are free. **Errors.** Every error is JSON: `{"error": "code", "message": "Plain-English explanation"}`. Codes are stable; messages may change. **Conventions.** JSON by default. Dates are `YYYY-MM-DD` and timestamps ISO 8601, all in UTC. Lane codes (`L1`) are case-insensitive. servers: - url: https://intentleads.si security: - bearerAuth: [] tags: - name: Exports description: Quote (free) and buy new people from your lanes, then download them. - name: Leads description: Pull and re-download the leads you've exported, and list deliveries. - name: Lanes description: >- Create, inspect and tune lanes: keywords plus the companies and roles you want. - name: Topics description: >- Topics we already track: live at once, with history. Use them before adding new keywords. - name: Keywords description: >- Add and remove a lane's keywords: existing topics, or new ones approved as their own topic. - name: Checks description: >- Free lane checks that size every filter step over 14 days, plus quick topic signals. - name: Company list description: >- The target-company list your lanes can narrow to or use instead of industries. - name: Exclusions description: Companies and people left out of every lane, before anything is bought. - name: Suppressions description: >- People you exported who later asked to be removed, by API or pushed to your webhook. - name: Webhooks description: >- Endpoints that receive events as they happen (removals, website visitors), signed, each with its own events, tests and delivery log. - name: Websites description: Identify the people who visit your websites. - name: Billing description: >- Your prepaid balance, prices and cost estimates (any key); top-ups and the monthly top-up (admin keys). - name: Team description: Members and invite links. Admin keys only. - name: Workspaces description: >- One workspace per client, all paid from your balance, with an optional monthly budget each; hand one over to the client. - name: API keys description: Create, rename, rotate and revoke API keys. Admin keys only. - name: Account description: Check which organization a key belongs to, and rename it. - name: Reference description: Valid values for lane filters. - name: Activity description: A feed of changes and events in your organization. paths: /api/v1/usage: get: tags: - Billing summary: Get usage (same as balance) description: |- Same as `GET /api/v1/billing/balance`, kept for older clients. **Free.** This doesn't spend your balance. operationId: getUsage responses: '200': description: The balance. content: application/json: schema: $ref: '#/components/schemas/Balance' example: balance_usd: 412.5 held_by_running_exports_usd: 20 available_usd: 392.5 expires_at: '2027-02-09T14:02:11.000Z' expiry_rule: >- The balance expires after 3 months with no top-up, grant or spending; any of those resets the clock. month: start: '2026-11-09' end: '2026-12-09' meters: intent: people_this_month: 2140 spent_usd: 214 price_now_cents: 10 next_price_drop: after_people: 2500 cents: 8 people_the_balance_covers: 4816 search: people_this_month: 0 spent_usd: 0 price_now_cents: 5 next_price_drop: after_people: 50000 cents: 4 people_the_balance_covers: 7850 this_organization: intent_leads: 2100 search_results: 0 website_visitors: 40 spent_usd: 214 paid_by: this_organization prices: intent: - from: 1 to: 2500 cents: 10 - from: 2501 to: 7500 cents: 8 - from: 7501 to: 20000 cents: 6.7 - from: 20001 to: null cents: 5 search: - from: 1 to: 50000 cents: 5 - from: 50001 to: 250000 cents: 4 - from: 250001 to: null cents: 2.5 note: >- Per person, marginal: the price falls as your organization (with its workspaces) uses more in a billing month, and resets next month. Website visitors use the intent prices. top_ups: presets_usd: - 250 - 500 - 1000 - 2500 - 10000 min_usd: 250 max_usd: 50000 how: >- POST /api/v1/billing/topups {"amount": 500} (admin key) returns a checkout_url. Automatic top-up: PUT /api/v1/billing/auto-topup {"enabled": true, "amount": 500, "threshold": 50}. '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' components: schemas: Balance: type: object properties: balance_usd: type: number description: >- Your organization's prepaid balance. Workspaces spend their organization's. Not shown to a workspace's own key (it may belong to a client): that gets `workspace_budget` instead, and none of the balance fields. held_by_running_exports_usd: type: number description: >- Held for exports still running; released when they finish, less the people delivered. available_usd: type: number description: '`balance_usd` less what''s held.' expires_at: type: - string - 'null' format: date-time description: >- When the balance expires unless something is added or spent first (3 months after the last top-up, grant or spending). Null when there's nothing to expire. expiry_rule: type: string description: The expiry rule in words. workspace_budget: type: object properties: budget_usd: type: - number - 'null' description: The monthly budget its organization set, or null for none. spent_usd: type: number description: Spent this billing month. held_usd: type: number description: Held for its exports still running. left_usd: type: - number - 'null' description: budget − spent − held, or null when there's no budget. note: type: string required: - budget_usd - spent_usd - held_usd - left_usd - note description: >- Only with a workspace's own key: what the workspace may spend each billing month, across intent leads, search results and website visitors. month: type: object properties: start: type: string format: date end: type: string format: date provisional: type: boolean description: >- Present before your first payment: months then start on that day. required: - start - end - provisional meters: type: object properties: intent: type: object properties: people_this_month: type: integer description: >- People charged on this meter this billing month, across your organization and its workspaces. spent_usd: type: number price_now_cents: type: number description: Price of the next person on this meter. next_price_drop: type: - object - 'null' description: >- Where the price drops next: `after_people` and the new `cents`. Null in the last tier. people_the_balance_covers: type: integer description: >- People the available balance buys now, at this month's prices. Not shown to a workspace's own key. required: - people_this_month - spent_usd - price_now_cents - next_price_drop search: type: object properties: people_this_month: type: integer description: >- People charged on this meter this billing month, across your organization and its workspaces. spent_usd: type: number price_now_cents: type: number description: Price of the next person on this meter. next_price_drop: type: - object - 'null' description: >- Where the price drops next: `after_people` and the new `cents`. Null in the last tier. people_the_balance_covers: type: integer description: >- People the available balance buys now, at this month's prices. Not shown to a workspace's own key. required: - people_this_month - spent_usd - price_now_cents - next_price_drop required: - intent - search description: Intent covers intent leads and website visitors. this_organization: type: object properties: intent_leads: type: integer search_results: type: integer website_visitors: type: integer spent_usd: type: number required: - intent_leads - search_results - website_visitors - spent_usd description: This organization (or workspace) alone, this month. paid_by: type: string enum: - this_organization - parent_organization monthly_topup: type: - object - 'null' description: >- Admin keys: the monthly top-up (`plan`, `amount_usd`, `status`, `renews_on`, `by_card`), or null. workspaces: type: array items: type: object properties: {} required: [] description: >- Admin keys of an organization with workspaces: each one's people and dollars this month and its budget (as in List workspaces). prices: type: object properties: intent: type: array items: type: object properties: from: type: integer to: type: - integer - 'null' cents: type: number required: - from - to - cents search: type: array items: type: object properties: from: type: integer to: type: - integer - 'null' cents: type: number required: - from - to - cents note: type: string required: - intent - search - note top_ups: type: object properties: presets_usd: type: array items: type: number min_usd: type: number max_usd: type: number how: type: string required: - presets_usd - min_usd - max_usd - how required: - month - meters - this_organization - paid_by - prices - top_ups example: balance_usd: 412.5 held_by_running_exports_usd: 20 available_usd: 392.5 expires_at: '2027-02-09T14:02:11.000Z' expiry_rule: >- The balance expires after 3 months with no top-up, grant or spending; any of those resets the clock. month: start: '2026-11-09' end: '2026-12-09' meters: intent: people_this_month: 2140 spent_usd: 214 price_now_cents: 10 next_price_drop: after_people: 2500 cents: 8 people_the_balance_covers: 4816 search: people_this_month: 0 spent_usd: 0 price_now_cents: 5 next_price_drop: after_people: 50000 cents: 4 people_the_balance_covers: 7850 this_organization: intent_leads: 2100 search_results: 0 website_visitors: 40 spent_usd: 214 paid_by: this_organization prices: intent: - from: 1 to: 2500 cents: 10 - from: 2501 to: 7500 cents: 8 - from: 7501 to: 20000 cents: 6.7 - from: 20001 to: null cents: 5 search: - from: 1 to: 50000 cents: 5 - from: 50001 to: 250000 cents: 4 - from: 250001 to: null cents: 2.5 note: >- Per person, marginal: the price falls as your organization (with its workspaces) uses more in a billing month, and resets next month. Website visitors use the intent prices. top_ups: presets_usd: - 250 - 500 - 1000 - 2500 - 10000 min_usd: 250 max_usd: 50000 how: >- POST /api/v1/billing/topups {"amount": 500} (admin key) returns a checkout_url. Automatic top-up: PUT /api/v1/billing/auto-topup {"enabled": true, "amount": 500, "threshold": 50}. Error: type: object properties: error: type: string example: lane_not_found description: Stable machine-readable code, e.g. `lane_not_found`. message: type: string example: No lane L9. description: Plain-English explanation you can show to a person. required: - error - message description: Every error has this shape. responses: Unauthorized: description: Missing, malformed, unknown or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: error: unauthorized message: 'Send a valid API key as: Authorization: Bearer il_live_…' InternalError: description: >- Unexpected server error. Safe to retry reads; retry an export only with the same `idempotency_key`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: value: error: internal_error message: Something went wrong. Try again. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: il_live_… description: >- An Intent Leads API key, e.g. `il_live_` followed by 32 letters and digits. Create one on the API and CLI page of the dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.