> ## Documentation Index > Fetch the complete documentation index at: https://docs.nmbr.co/llms.txt > Use this file to discover all available pages before exploring further. # Usage > Query usage records and summaries for billing Usage data helps partners reconcile payroll activity to billing. Nmbr exposes usage in two levels of detail: * `usage_records`: the individual billable events Nmbr recorded. * `usage_summaries`: monthly rollups of those records by company and event type. Use usage summaries when you need invoice totals. Use usage records when you need to explain or reconcile a specific count. ## How usage is counted Usage summaries are based on when a usage record was recorded, not on the payroll period the payroll represents. For payroll-related usage, this means the count lands in the month when the payroll activity is processed and recorded by Nmbr. If you process historical or backdated payrolls in May, the resulting usage records are counted in May, even if those payrolls represent work from March or April. Example: * On May 7, you process an April payroll for 15 employees. * Nmbr records the paid employee usage on May 7. * The `employee_paid` count appears in the May usage summary. * It does not appear in the April usage summary. This timing rule is the same reason usage records include `recorded_at`: if a summary count looks unexpected, inspect the underlying records and compare their `recorded_at` timestamps. ## Usage event types Each usage summary has an `event` and a `count`. These are the usage event types Nmbr currently returns: | Event | What it counts | | ------------------------ | --------------------------------------------------------------- | | `employee_paid` | Employee pay stubs paid during the usage month. | | `contractor_paid` | Contractor pay stubs paid during the usage month. | | `employee_paid_unique` | Unique employees paid during the usage month. | | `contractor_paid_unique` | Unique contractors paid during the usage month. | | `funding_failure` | Billable funding failures recorded during the usage month. | | `payroll_expedited` | Expedited payrolls paid during the usage month. | | `kyb_attempt` | Business verification attempts recorded during the usage month. | | `business_launched` | Businesses that launched during the usage month. | Partners billed per employee per pay run usually reconcile against `employee_paid` and `contractor_paid`. Partners billed per employee per month usually reconcile against `employee_paid_unique` and `contractor_paid_unique`. ## Get monthly usage summaries Use `GET /usage_summaries` to retrieve monthly rollups. Usage endpoints are partner-level endpoints, so authenticate with your partner secret. ```bash theme={null} curl --request GET \ --url "https://sandbox.nmbr.co/services/payroll/usage_summaries?company_id=cmp_123&period_start=2025-05-01&period_end=2025-05-31" \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' ``` **Response** ```json theme={null} { "object": "list", "data": [ { "id": "usum_123", "object": "usage_summary", "data": { "company": { "id": "cmp_123", "object": "company", "links": { "self": "/companies/cmp_123" } }, "event": "employee_paid", "count": 15, "period_start": "2025-05-01", "period_end": "2025-05-31", "created_at": "2025-05-07T20:11:32.000000Z", "updated_at": "2025-05-07T20:11:32.000000Z" }, "links": { "self": "/usage_summaries/usum_123" } }, { "id": "usum_456", "object": "usage_summary", "data": { "company": { "id": "cmp_123", "object": "company", "links": { "self": "/companies/cmp_123" } }, "event": "contractor_paid_unique", "count": 8, "period_start": "2025-05-01", "period_end": "2025-05-31", "created_at": "2025-05-07T20:11:32.000000Z", "updated_at": "2025-05-07T20:11:32.000000Z" }, "links": { "self": "/usage_summaries/usum_456" } } ] } ``` Nmbr creates one summary row per company, month, and event type. Events with no usage may still appear with a count of `0`. ## Reconcile a summary with usage records Use `GET /usage_records` to inspect the records that feed a summary. Filter by the same company and the recorded date range for the month you are reconciling. ```bash theme={null} curl --request GET \ --url "https://sandbox.nmbr.co/services/payroll/usage_records?company_id=cmp_123&recorded_at%5Bgte%5D=2025-05-01&recorded_at%5Blt%5D=2025-06-01" \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' ``` **Response** ```json theme={null} { "object": "list", "data": [ { "id": "urec_123", "object": "usage_record", "data": { "company": { "id": "cmp_123", "object": "company", "links": { "self": "/companies/cmp_123" } }, "event": "employee_paid", "record": { "id": "pay_stub_123", "object": "pay_stub", "links": { "self": "/pay_stubs/pay_stub_123" } }, "recorded_at": "2025-05-07 20:11:32", "created_at": "2025-05-07T20:11:32.000000Z", "updated_at": "2025-05-07T20:11:32.000000Z" }, "links": { "self": "/usage_records/urec_123" } } ] } ``` If a payroll was processed in May for an April pay period, the usage record still has a May `recorded_at` timestamp and contributes to the May summary. ## Practical reconciliation flow 1. Fetch `GET /usage_summaries` for the company and month you want to invoice. 2. Group the returned rows by `event`. 3. Use `employee_paid` plus `contractor_paid` for per-pay-run billing. 4. Use `employee_paid_unique` plus `contractor_paid_unique` for per-month billing. 5. If a count is unexpected, fetch `GET /usage_records` for the same company and recorded month, then inspect the `event`, `record`, and `recorded_at` values.