> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/objects/timeline-event.md).

# The timeline event object

The timeline event object in the Shortcut API - every field, an example, and the endpoints that return it.

One thing that happened with a customer, as the profile's Activity tab shows it.

## Fields

| Field                    | Type                                                                                                  | Description                                                                                                                                                                               |
| ------------------------ | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | string                                                                                                | The event's id, stable across reads.                                                                                                                                                      |
| `object`                 | `"timeline_event"`                                                                                    | Always `timeline_event`.                                                                                                                                                                  |
| `kind`                   | string                                                                                                | What happened, e.g. `job_completed`, `sms_received`, `estimate_approved`, `invoice_paid`, `note`, `photo`, `task`. New kinds can appear; treat an unknown kind as a generic event.        |
| `group`                  | `comments`, `visits`, `messages`, `estimates`, `billing`, `automations`, `tasks`, `chemicals`, `lead` | The filter the profile's Activity tab files the event under.                                                                                                                              |
| `occurredAt`             | timestamp                                                                                             | When it happened, ISO 8601 in UTC.                                                                                                                                                        |
| `title`                  | string                                                                                                | The one-line summary the profile shows.                                                                                                                                                   |
| `detail`                 | string                                                                                                | More text when the event has it (a note's or message's text); empty otherwise. A note's text needs `notes:read`: without it a note event's title is `Note added` and its detail is empty. |
| `authorName`             | string or null                                                                                        | Who did it, when a person did.                                                                                                                                                            |
| `attachments`            | array of objects                                                                                      | Photos, videos, and files on the event.                                                                                                                                                   |
| `attachments[].id`       | id                                                                                                    | The attachment's id; `GET /v1/attachments/{id}` returns a download link.                                                                                                                  |
| `attachments[].source`   | `activity_post`, `visit`, `estimate`, `inbox_email`, `project`                                        | Where the file lives.                                                                                                                                                                     |
| `attachments[].type`     | `photo`, `video`, `file`                                                                              | Photo, video, or any other file.                                                                                                                                                          |
| `attachments[].filename` | string or null                                                                                        | The file's name, when the event carries it.                                                                                                                                               |
| `taskId`                 | id or null                                                                                            | The task, for task events.                                                                                                                                                                |
| `activityPostId`         | id or null                                                                                            | The activity post, for posts on the feed.                                                                                                                                                 |
| `visitIds`               | array of id                                                                                           | The visits a visit event stands for (a visit can group several services).                                                                                                                 |
| `viaApp`                 | string or null                                                                                        | The connected app or API token whose change made this event, e.g. `Grok`; null when a person, the customer, or Shortcut did.                                                              |

## Example

```json
{
  "id": "Example id",
  "object": "timeline_event",
  "kind": "Example kind",
  "group": "comments",
  "occurredAt": "2026-10-16T17:04:12.381Z",
  "title": "Example title",
  "detail": "Example detail",
  "authorName": "Example authorName",
  "attachments": [
    {
      "id": "4a056725-464f-426c-8299-ddb33ee418fa",
      "source": "activity_post",
      "type": "photo",
      "filename": "Example filename"
    }
  ],
  "taskId": "a4c81b3a-a112-4681-8d5c-91c899a6cd0f",
  "activityPostId": "ef47e1e8-eb92-4d2f-87dc-5876e42693bd",
  "visitIds": [
    "186f7297-14b9-4dde-8103-e9250d4e246c"
  ],
  "viaApp": "Example viaApp"
}
```

## Endpoints

| Endpoint                          | What it does               |
| --------------------------------- | -------------------------- |
| `GET /v1/customers/{id}/timeline` | List a customer's timeline |
| `GET /v1/leads/{id}/timeline`     | List a lead's timeline     |
