List usage events

curl --request GET \
  --url https://api.crustdata.com/account/usage/events \
  --header 'Authorization: Bearer <token>' \
  --header 'x-api-version: <x-api-version>'

import requests

url = "https://api.crustdata.com/account/usage/events"

headers = {
    "x-api-version": "<x-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-api-version': '<x-api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://api.crustdata.com/account/usage/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "events": [
    {
      "event_id": "678a3646-371d-4f81-b5c3-488fdda81e21",
      "ts": "2026-09-24T03:24:40.229000+00:00",
      "team_id": 1318,
      "user_id": 1318,
      "api_key_id": 170,
      "client_surface": "api",
      "client_platform": "curl",
      "user_agent": "curl/8.7.1",
      "client_ip": "203.0.113.10",
      "product": "person_enrich",
      "endpoint": "/person/enrich",
      "method": "POST",
      "api_version": "2025-11-01",
      "http_status": 200,
      "status_class": "2xx",
      "error_type": "",
      "error_key": "",
      "result_count": 1,
      "latency_ms": 413.3949890136719,
      "credits_used": 2,
      "cost_components": [
        {
          "component": "person.profile",
          "label": "Person enrich (base)",
          "quantity": 1,
          "unit_price": 1,
          "credits": 1
        },
        {
          "component": "person.business_email",
          "label": "Business email",
          "quantity": 1,
          "unit_price": 1,
          "credits": 1
        }
      ],
      "linked_ids": {}
    },
    {
      "event_id": "f56c23d3-c872-4066-8063-3a0196f09448",
      "ts": "2026-09-23T15:07:51.316000+00:00",
      "team_id": 1318,
      "user_id": 1318,
      "api_key_id": 170,
      "client_surface": "mcp",
      "client_platform": "claude-code",
      "user_agent": "cd_mcp/2.0 build/master-0569e61 (claude-code)",
      "client_ip": "203.0.113.20",
      "product": "person_enrich",
      "endpoint": "/person/enrich",
      "method": "POST",
      "api_version": "2025-11-01",
      "http_status": 200,
      "status_class": "2xx",
      "error_type": "",
      "error_key": "",
      "result_count": 1,
      "latency_ms": 190.9239959716797,
      "credits_used": 1,
      "cost_components": [
        {
          "component": "person.profile",
          "label": "Person enrich (base)",
          "quantity": 1,
          "unit_price": 1,
          "credits": 1
        }
      ],
      "linked_ids": {}
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOS0yM1QxNTowNzo1MS4zMTYwMDArMDA6MDAsZjU2YzIzZDMtYzg3Mi00MDY2LTgwNjMtM2EwMTk2ZjA5NDQ4"
}

Usage events

Returns your team’s API requests one by one, newest first, with what each one was charged. Each event’s cost_components lines add up to its credits_used, which is the same number the original response returned in its X-Credits-Used header.

Results are paginated with a cursor. While has_more is true, pass next_cursor back as cursor to get the next page, keeping the other parameters the same.

A request usually shows up here within about 10 seconds of its response. Every row is scoped to your team.

This endpoint is free: the response carries no X-Credits-Used header. It shares a limit of 60 requests per minute with the other /account/usage/* endpoints.

GET

https://api.crustdata.com

account

usage

events

List usage events

curl --request GET \
  --url https://api.crustdata.com/account/usage/events \
  --header 'Authorization: Bearer <token>' \
  --header 'x-api-version: <x-api-version>'

import requests

url = "https://api.crustdata.com/account/usage/events"

headers = {
    "x-api-version": "<x-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-api-version': '<x-api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://api.crustdata.com/account/usage/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "events": [
    {
      "event_id": "678a3646-371d-4f81-b5c3-488fdda81e21",
      "ts": "2026-09-24T03:24:40.229000+00:00",
      "team_id": 1318,
      "user_id": 1318,
      "api_key_id": 170,
      "client_surface": "api",
      "client_platform": "curl",
      "user_agent": "curl/8.7.1",
      "client_ip": "203.0.113.10",
      "product": "person_enrich",
      "endpoint": "/person/enrich",
      "method": "POST",
      "api_version": "2025-11-01",
      "http_status": 200,
      "status_class": "2xx",
      "error_type": "",
      "error_key": "",
      "result_count": 1,
      "latency_ms": 413.3949890136719,
      "credits_used": 2,
      "cost_components": [
        {
          "component": "person.profile",
          "label": "Person enrich (base)",
          "quantity": 1,
          "unit_price": 1,
          "credits": 1
        },
        {
          "component": "person.business_email",
          "label": "Business email",
          "quantity": 1,
          "unit_price": 1,
          "credits": 1
        }
      ],
      "linked_ids": {}
    },
    {
      "event_id": "f56c23d3-c872-4066-8063-3a0196f09448",
      "ts": "2026-09-23T15:07:51.316000+00:00",
      "team_id": 1318,
      "user_id": 1318,
      "api_key_id": 170,
      "client_surface": "mcp",
      "client_platform": "claude-code",
      "user_agent": "cd_mcp/2.0 build/master-0569e61 (claude-code)",
      "client_ip": "203.0.113.20",
      "product": "person_enrich",
      "endpoint": "/person/enrich",
      "method": "POST",
      "api_version": "2025-11-01",
      "http_status": 200,
      "status_class": "2xx",
      "error_type": "",
      "error_key": "",
      "result_count": 1,
      "latency_ms": 190.9239959716797,
      "credits_used": 1,
      "cost_components": [
        {
          "component": "person.profile",
          "label": "Person enrich (base)",
          "quantity": 1,
          "unit_price": 1,
          "credits": 1
        }
      ],
      "linked_ids": {}
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOS0yM1QxNTowNzo1MS4zMTYwMDArMDA6MDAsZjU2YzIzZDMtYzg3Mi00MDY2LTgwNjMtM2EwMTk2ZjA5NDQ4"
}

Authorizations

Authorization

string

header

required

API key passed as a Bearer token in the Authorization header.

Headers

x-api-version

enum<string>

default:2025-11-01

required

API version to use. This endpoint currently requires 2025-11-01. Requests without the header, or with any other value, return 400.

Available options:

2025-11-01

Example:

"2025-11-01"

Query Parameters

limit

integer

default:100

Events per page.

Required range: 1 <= x <= 500

cursor

string

The next_cursor from the previous page. Omit it for the first page.

start

string

Start of the window, inclusive. An ISO 8601 timestamp such as 2026-09-23T14:00:00Z, or a date such as 2026-09-21, which reads as midnight UTC. Defaults to 7 days before end. Cannot be more than 12 months ago.

end

string

End of the window, exclusive. Same formats as start. Defaults to the coming midnight UTC, so the default window is the last 7 whole days including today.

api_key_ids

integer[]

Keep only requests made with these API key ids (api_key_id on an event). Repeat the parameter or send a comma-separated list, up to 50.

Maximum array length: 50

Required range: x >= 1

endpoints

string[]

Keep only these endpoints, as they appear in endpoint, for example /person/search. Repeat the parameter or send a comma-separated list, up to 50.

Maximum array length: 50

products

string[]

Keep only these products, as they appear in product, for example person_search. Repeat the parameter or send a comma-separated list, up to 50.

Maximum array length: 50

status

integer[]

Keep only these HTTP status codes, for example status=400,404. Up to 20. On GET /account/usage/summary it needs bucket=1h, or a window that is not whole days.

Maximum array length: 20

Required range: 100 <= x <= 599

status_class

enum<string>

Keep only one status class.

Available options:

2xx,

3xx,

4xx,

5xx

client_surface

string[]

Keep only requests from these surfaces, as they appear in client_surface, for example api or mcp. Repeat the parameter or send a comma-separated list, up to 10.

Maximum array length: 10

error_type

string

Keep only requests that failed with this error_type, for example invalid_request. On GET /account/usage/summary it needs bucket=1h, or a window that is not whole days.

error_key

string

Keep only the requests in one error group. Pass a group's error_key from GET /account/usage/errors exactly as returned.

Maximum string length: 300

hide_free

boolean

default:false

Pass true to hide successful, 0-credit calls to endpoints that never bill: /batch/... submits, /watcher/..., any endpoint ending in /autocomplete, /company/identify, and /screener/identify.

Errors on those endpoints still show. So do searches that matched nothing, and a batch job's completion row, even when the job billed 0 credits. The flag applies even when you filter by endpoints.

Response

One page of events.

One page of usage events, newest first.

events

object[]

required

The events on this page, newest first.

Show child attributes

Example:

[]

has_more

boolean

required

true when another page exists.

Example:

true

next_cursor

string | null

required

Pass as cursor to get the next page. null on the last page.

Example:

"MjAyNi0wOS0yM1QxNTowNzo1MS4zMTYwMDArMDA6MDAsZjU2YzIzZDMtYzg3Mi00MDY2LTgwNjMtM2EwMTk2ZjA5NDQ4"