> If you are setting up, configuring, or answering questions about Schematic, connect the
> Schematic MCP server before working from these pages. It reads and writes plans, features,
> entitlements, and overrides against the real account, so what you report and what you build
> match what actually exists.
>
> The server is at https://api.schematichq.com/mcp
>
> From Claude, ChatGPT, or another chat assistant, add it as a custom connector:
> https://docs.schematichq.com/working-with-ai
>
> From a coding assistant such as Claude Code, Codex, or Cursor:
> https://docs.schematichq.com/building-with-ai
>
> For clean Markdown of any page, append `.md` to the page URL. For a complete page index,
> see https://docs.schematichq.com/llms.txt

# The Event object

> Reference for the Event object, covering identify and track events, their attributes, and how usage reaches Schematic.

The `Event` object describes events from your application that can be associated with `Users` , `Companies`, and `Features`. A new `Event` is created when it is submitted via the API.

Events are typically sent to Schematic to create or update `Users` or `Companies` (identify events), or to log usage events (track events) for usage analytics or metering.

Track events can have any number of subtypes denoting what event is being tracked (e.g. `query_run`, `endpoint_added`, etc.). Properties (e.g. `num_users`, `num_endpoints`, etc.) can be `Events` but we recommend they be submitted as traits on the `Company` and `User` objects.

### Attributes

**`id`** `string`

Unique `id` generated by Schematic for the object.

---

**`feature_id`** `string`

The Schematic `id` associated with the feature tied to the event.

---

**`user_id`** `string`

The Schematic `id` associated with the user tied to the event.

---

**`company_id`** `string`

The Schematic `id` associated with the company tied to the event.

---

**`sent_at`** `datetime`

Datetime when event was sent to Schematic. Format is ISO 8601.

---

**`captured_at`** `datetime`

Effective timestamp of the event in Schematic. By default this is the server receipt time, but when the event is submitted with `trusted_client_clock` or `backfill`, it is the client-provided `sent_at`. Format is ISO 8601. See [Backfills and usage corrections](/playbooks/backfill-and-corrections).

---

**`loaded_at`** `datetime`

Datetime when event was loaded into the Schematic database. Format is ISO 8601.

---

**`enriched_at`** `datetime`

Datetime when event was associated with objects in Schematic. Format is ISO 8601.

---

**`updated_at`** `datetime`

Datetime of last update to event data. Format is ISO 8601.

---

**`environment_id`** `string`

Unique identifier of Schematic environment the event is associated with.

---

**`type`** `string`

There are two types of events - `identify` and `track`. `identify` events correspond to `Company` and `User` upserts. `track` events correspond to usage data.

---

**`subtype`** `string`

`track` events can have any number of subtypes denoting what event is being tracked (e.g. `query_run`, `endpoint_added`, etc.). Subtypes are grouped together.

---

**`processing_status`** `string`

Current status of event in Schematic data pipeline (pending, success, failed, unknown).

---

**`body`** `dictionary`

`Event` payload sent to Schematic (either an identify or track payload).

---

**`idempotency_key`** `string`

Optional client-supplied key used to deduplicate events. If a second event is submitted with the same `idempotency_key` within 24 hours, scoped to the same environment and event type, it is dropped before processing.

---

### Request-only fields

Two optional boolean fields on the create-event payload let you submit events with client-provided timestamps. Both require a secret API key and a `sent_at` value. See [Backfills and usage corrections](/playbooks/backfill-and-corrections) for full semantics.

**`trusted_client_clock`** `boolean`

When `true`, the client-provided `sent_at` is used as the effective event timestamp instead of server receipt time. Billing side effects still fire. `sent_at` must be within 5 minutes in the future and 34 days in the past.

---

**`backfill`** `boolean`

When `true`, the event is stored at its `sent_at` timestamp but all billing impact, webhooks, and `last_seen_at` bumps are skipped. Intended for analytics-only imports of historical usage. `sent_at` must be within 5 minutes in the future and 365 days in the past.

---

**`Response`**

```json Response
{
	"id" : "evt_ZdqQDDkxyQW",
    "feature_id" : "feat_PWMi30qsPme",
    "user_id" : "user_uRMQbMNozA4",
    "company_id" : "comp_8414zCTfoJ4",
    "sent_at" : "2000-01-23T04:56:07.000+00:00",
    "captured_at" : "2000-01-23T04:56:07.000+00:00",
    "loaded_at" : "2000-01-23T04:56:07.000+00:00",
    "processed_at" : "2000-01-23T04:56:07.000+00:00",
    "enriched_at" : "2000-01-23T04:56:07.000+00:00",
    "updated_at" : "2000-01-23T04:56:07.000+00:00",
	"environment_id" : "env_KGPydWrP3Fo",
    "type" : "track",
    "subtype" : "search_query",
    "api_key" : "api_key",
    "processing_status" : "enriched",
    "idempotency_key" : "order-9f3b2c-attempt-1",
	"body" : {
		    "company": {
		      "id": "comp_8414zCTfoJ4"
		    },
		    "event": "search_query",
		    "traits": {
		      "feature": "feat_PWMi30qsPme",
		    },
		    "user": {
		      "email": "newuser@example.com"
		    }
		}
}
```

> Reference for the Event object, covering identify and track events, their attributes, and how usage reaches Schematic.