---
title: Send Usage Events
slug: send-usage-events
docTags: 
createdAt: 2026-10-20T00:08:11.630Z
---

Stream usage events into Nue for metering. Events are batched, deduplicated by your own id, and durably queued for aggregation and rating.

## Endpoint

```text
POST https://metering.nue.io/v1/metering/events
```

**Permission:** Gated by the Metering license.

## Limits

- Up to **1000 events** per request.
- Up to **256 KB** per request.
- At least one event per request.

## Request body

```text
{ "data": [ <event>, … ] }
```

Each event:

| Field                          | Type              | Required          | Notes                                                                                       |
| ------------------------------ | ----------------- | ----------------- | ------------------------------------------------------------------------------------------- |
| `transactionId`                | string            | Yes               | Your unique id for this event. This is the deduplication key.                               |
| `subscriptionNumber`           | string            | Identity option A | The subscription the usage belongs to. Do not combine with the customer and product fields. |
| `customerId` or `customerName` | string            | Identity option B | The customer, by id or name. Pair with a product field.                                     |
| `sku` or `productName`         | string            | Identity option B | The product, by SKU or name. Pair with a customer field.                                    |
| `timestamp`                    | string            | Yes               | RFC3339 with an explicit timezone or UTC offset.                                            |
| `value` or `quantity`          | number            | Yes, exactly one  | Whole numbers only. Supplying both is rejected.                                             |
| `properties`                   | object of strings | Yes               | Pricing and usage dimension values. Keys must not reuse reserved field names.               |
| `tags`                         | object of strings | No                | Filter only labels. Same reserved key rule.                                                 |
| `specVersion`                  | string            | No                | Contract major version. Only major `1` is served.                                           |

Identify each event one of two ways: by `subscriptionNumber`, or by a customer field (`customerId` or `customerName`) together with a product field (`sku` or `productName`). Do not mix the two ways on one event.

**Reserved keys** (rejected inside `properties` or `tags`): `transactionId`, `subscriptionNumber`, `customerId`, `customerName`, `sku`, `productName`, `timestamp`, `value`, `quantity`.

## Response

`202 Accepted` with an empty body. The batch is durably queued.

**Acceptance is not resolution.** A `202` means the events are queued, not that they will be priced. An event whose subscription cannot be resolved is discarded downstream. Duplicate `transactionId`s are accepted here and suppressed at read and rating time: the first event for a `transactionId` wins, and a resend never double counts and never errors.

A malformed batch returns `400` with the standard error envelope. Per event problems carry codes that name the offending field: `MISSING_FIELD`, `MISSING_IDENTITY`, `CONFLICTING_IDENTITY`, `DUPLICATE_VALUE_FIELD`, `INVALID_TIMESTAMP`, `INVALID_VALUE`, `RESERVED_KEY`.

## Example

```text
curl --request POST \
  --url https://metering.nue.io/v1/metering/events \
  --header 'nue-api-key: <your-key>' \
  --header 'content-type: application/json' \
  --data '{
    "data": [
      {
        "transactionId": "evt_01K5V8N2Q7",
        "subscriptionNumber": "SUB-000042",
        "timestamp": "2026-09-16T14:03:22Z",
        "value": 18432,
        "properties": { "model": "claude-opus", "region": "us-east-1" },
        "tags": { "userId": "u_8814" }
      }
    ]
  }'
```

```text
202 Accepted
```

See [Realtime Usage Feed](docId\:B5C8JPbJDYlSxqJYgL5gs) to read the rated results as they move, and [Metering Overview](docId\:Lnp1sevEW6CqyiN46S4fp) for auth, hosts, and data conventions.