> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trycurious.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and attribution

> An event is what a user did: how its name, properties, value and timestamp are read, and how it attributes to the decision before it.

An **event** is a fact about what a user did: `purchased`, `clicked`, `signed_up`. You report events as they happen; Curious attributes each one to the decisions that preceded it and learns from the result.

```json theme={null}
{
  "user_id": "user_123",
  "name": "purchased",
  "value": 49.99,
  "properties": { "plan": "pro" },
  "context": { "device": "mobile" },
  "timestamp": "2026-04-30T22:33:42Z",
  "id": "ord_8f3a_purchased"
}
```

## The fields

* **`name`**: past tense, matched exactly against the names in your rewards and constraints. Use one name with properties rather than many names: `email_opened` with `{ "email_name": "welcome" }`, not `welcome_email_opened`, so a reward can match the whole family or one member. Names starting with `$` are reserved for the browser SDK's own system events.
* **`value`**: optional, defaults to 1 (`null` also means 1). The amount for a `semicontinuous` or `continuous` reward; ignored by `binary` and counted once by `count`.
* **`properties`**: facts about the event. Rewards and constraints can filter on them. Never written to the user.
* **`context`**: the situation at event time, such as device or page. Kept with the event, not a filter, not written to the user.
* **`timestamp`**: when the event happened. Defaults to the moment it is received. Declare it for buffered or backfilled events so a late event still attributes to the right decision.
* **`id`**: your idempotency key for this event. A repeat is deduplicated. See [Idempotency](https://docs.trycurious.ai/api-reference/idempotency.md).

## How an event attributes

Attribution is by user and by window. An event for `user_123` named `purchased` attributes to the decision made for `user_123` on an element whose rewards or constraints name `purchased` (and whose `properties` filter, if any, matches), provided the event's `timestamp` falls inside that decision's window: from the decision until `window_seconds` later, or until a newer decision for the same user and element ended it. Each event lands in exactly one window per element, so nothing is double-counted and no touch-attribution rule is needed.

Three consequences follow:

1. **Use the same `user_id` you decided with.** An event under a different id attributes to nothing until [`identify`](https://docs.trycurious.ai/guides/identify) links the two.
2. **Report events for every user, including the ones Curious did not decide for.** Attribution finds the decision if there is one; an event without a preceding decision is simply stored.
3. **Timestamps matter.** A buffered event sent an hour late with no `timestamp` is attributed at receipt time and may fall outside its window. Send the real time.

## Two environments

An event reported under a test key belongs to a test user and attributes only to test decisions. See [Keys and environments](https://docs.trycurious.ai/guides/keys.md).

## Reporting events

The request shapes, the batch form of up to 200 events, and the response are on [Track outcomes](https://docs.trycurious.ai/guides/events.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.