Log in Get an API key

API Reference › Account

Usage Analytics (v2)

GET /v2/api/analytics/usage/

Cost: Free.

Rate limit: No limit.

Mode: Sync

The richer successor to Analytics: usage for every billed service, a credits-used trend for charting, and your balance and plan. Recommended for new integrations. v1 is not deprecated and stays available, unchanged, for existing integrations. usage is a flat array of service objects, not one fixed key per service, so new services can be added later without breaking integrations that iterate it. Every billed service appears, even with zero usage; the example below shows four of them. Each object has service_key, category, label, requests, hits, misses, credits and rate (credits per hit), plus service-specific extras such as jobs (batch jobs), clean (DNC phones not on any list), lists (lead lists) or permits (permits found). jobs vs. lists vs. neither: jobs only appears on batch services (trace.*, dnc.batch, parcel.batch). It counts how many separate upload jobs you ran, since each one processes many rows in the background. Single-request lookup services (instant_trace, phone_verify, dnc.lookup, etc.) have no jobs field: each request is already the unit, so it would just repeat requests. lists plays the same role for lead_builder.* (a Lead Builder list is that service's batch unit), and ai_assist has neither, since every call stands alone. Period: with no dates, figures cover all time and may lag by up to 90 seconds (cached). With start_date and/or end_date, figures are computed live; both dates are inclusive and either side may be left open. Trend: trend.points holds one entry per bucket, including empty ones. With granularity=auto, buckets are daily up to 90 days, weekly beyond that, monthly for spans over two years and yearly for spans over four years. All time is monthly, or yearly when your history goes back more than four years, so the chart doesn't turn into dozens of hard-to-read monthly bars. Errors: 400 when a date is not YYYY-MM-DD, when start_date is after end_date, or when granularity is not one of the allowed values. Related endpoints: Usage Analytics

Fields

Responses