---
title: "Record an event"
description: "Record a customer action or update customer properties."
api: POST https://i.nuxie.ai/event
authMethod: none
playground: simple
search:
  tags: ["api", "app", "reference"]
  keywords: ["capture", "trigger", "uuid", "idempotency_key", "$set", "$set_once", "$unset", "$increment"]
---

Record a customer action, update customer properties, or send an event used by an Experience trigger. Use a stable UUID so retries do not record the action twice.

## Request body

- **`apiKey`** · body · `string` · required

  Publishable key for the app platform. A `pk_test_` key selects test data; a `pk_live_` key selects live data. Copy it from **Connect your app**.

- **`event`** · body · `string` · required

  Non-empty event name. Names starting with `$` are [system events](/docs/api-reference/system-events), recorded by the SDK and platform.

- **`distinct_id`** · body · `string` · required

  The identified or anonymous customer ID your app supplies to the SDK, rather than Nuxie's internal customer record ID. See [Customer identifiers](/docs/api-reference/rest-api#customer-identifiers).

- **`properties`** · body · `object`

  Values describing this event. Supports the customer-property directives below.

- **`timestamp`** · body · `string`

  ISO 8601 timestamp for when the event happened.

- **`uuid`** · body · `string`

  Valid UUID for the event. Required unless you supply `idempotency_key`; reuse the same value for retries.

- **`idempotency_key`** · body · `string`

  Alternative to `uuid`, also a valid UUID.

- **`value`** · body · `number`

  Numeric value associated with the event.

- **`entityId`** · body · `string`

  Entity identifier for entity-scoped Feature activity.

- **`$anon_distinct_id`** · body · `string`

  Prior anonymous identity during an identify merge.

## Customer properties

An event's `properties` describe that occurrence. These directives inside `properties` also update the customer profile:

| Directive | Value | Behavior |
| --- | --- | --- |
| `$set` | Object | Set or replace customer properties |
| `$set_once` | Object | Set properties only when they don't already exist |
| `$unset` | Array of property names | Remove customer properties |
| `$increment` | Object of numeric amounts | Add each amount to the current numeric value, starting from zero when absent |

For example:

```json
{
  "source": "settings",
  "$set": { "plan": "pro" },
  "$set_once": { "signup_source": "referral" },
  "$unset": ["onboarding_step"],
  "$increment": { "exports_created": 1 }
}
```

Use one directive per property in a request. See [Customer properties](/docs/guides/customer-properties) for targeting with these values.

## Response

- **`status`** · `string` · required

  `ok` for an accepted ordinary app event.

- **`eventId`** · `string` · required

  Event UUID.

- **`customerIdHint`** · `string` · required

  Nuxie customer record hint; keep using your own customer ID in requests.

- **`accepted`** · `integer` · required

  Number of accepted events: `1`.

- **`queued`** · `boolean` · required

  `true` confirms the event was accepted for processing.

- **`payload`** · `object` · required

  Supported event fields after normalization.

Customer profiles, analytics, and server-side delivery update as the event is processed. The response confirms receipt, rather than completion of those updates.

Reuse the event UUID if a request times out. A new UUID records another occurrence. To change paid access or spend units, use the [purchase](/docs/api-reference/app/purchase) and [Feature usage](/docs/api-reference/app/consume) endpoints; an analytics event alone does not authorize those changes.

```sh title="cURL"
curl https://i.nuxie.ai/event \
  --header 'Content-Type: application/json' \
  --data '{
  "apiKey": "pk_test_example",
  "event": "export_limit_reached",
  "distinct_id": "user-456",
  "properties": {
    "limit": 10,
    "$set": { "plan": "free" }
  },
  "timestamp": "2026-08-21T12:00:00Z",
  "uuid": "018f55a9-9ec4-7d7a-9b4a-1dbe8cc58410"
}'
```

```json title="200"
{
  "status": "ok",
  "eventId": "018f55a9-9ec4-7d7a-9b4a-1dbe8cc58410",
  "customerIdHint": "customer-record-id",
  "accepted": 1,
  "queued": true,
  "payload": {
    "apiKey": "pk_test_example",
    "event": "export_limit_reached",
    "distinct_id": "user-456",
    "properties": {
      "limit": 10,
      "$set": { "plan": "free" }
    },
    "timestamp": "2026-08-21T12:00:00Z",
    "uuid": "018f55a9-9ec4-7d7a-9b4a-1dbe8cc58410"
  }
}
```