Retrieve an event

Fetch one event by its id or its name.

GET /v1/events/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The event id (evt_…) or the event name (user.created). Either resolves to the same event.

Example

curl

# by id
curl "https://api.sendgrail.com/v1/events/evt_3nBq7Ld2KeR9" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

# or by name — the same event
curl "https://api.sendgrail.com/v1/events/user.created" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

const res = await fetch('https://api.sendgrail.com/v1/events/user.created', {
  headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
});

const event = await res.json();

Response

{
  "object": "event",
  "id": "evt_3nBq7Ld2KeR9",
  "name": "user.created",
  "schema": {
    "plan": "string",
    "seats": "number",
    "trial": "boolean",
    "signed_up_at": "date"
  },
  "created_at": "2026-07-14T19:44:32+00:00",
  "updated_at": "2026-07-14T19:44:32+00:00"
}

For what each field means, see The event object. An event with no schema returns "schema": null.

The name works as a path parameter

Because the event name is unique within your team, it identifies the event just as well as the id does — GET /v1/events/user.created and GET /v1/events/evt_3nBq7Ld2KeR9 return the same object. Sending the name saves you looking the id up first, the same way a contact endpoint accepts an email address in place of an id.

An event belonging to another team answers 404, not 403 — an id that isn't yours is an id that doesn't exist, as far as your key is concerned. A Sending-access key answers 403: it is a real key, it just isn't allowed to read the event registry. See Errors.