# Create timeline entry

Add a new status update to an event's public timeline.

Source: https://statusdashboard.com/docs/api/event-management/events/timeline/create

`POST /app/events/{id}/timeline`

Adds a new timeline entry to the event and updates the event's current status. Returns the full updated event object.

Timeline entries apply to **incidents and maintenance events** only. Informational events do not have a timeline.

***

## Path parameters
| Parameter | Description   |
| --------- | ------------- |
| `id`      | The event ID. |

***

## Request
See [API Basics](/docs/api) for required headers.

### Request body
| Field         | Type   | Required | Description                                                                                                                                               |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `statusLabel` | string | Yes      | A workflow phase label valid for this event type.                                                                                                         |
| `message`     | string | Yes      | The status message. Rich text field. See [Rich text fields](/docs/api#rich-text-fields). Max 5,000 characters.                                            |
| `timestamp`   | string | No       | ISO 8601 UTC datetime. Defaults to the current time. Cannot be in the future. Use this to record an update that happened before you were able to post it. |

***

## Sample request
```bash
curl -X POST https://api.statusdashboard.com/app/events/4f8b2e1a-3c7d-4e9f-a0b1-c2d3e4f56789/timeline \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "statusLabel": "Identified",
    "message": "Root cause identified as a misconfigured load balancer rule. Fix is being deployed."
  }'
```

## Sample response
**Status: `201 Created`**

```json
{
  "event": {
    "id": "4f8b2e1a-3c7d-4e9f-a0b1-c2d3e4f56789",
    "eventType": "incident",
    "title": "API latency elevated",
    "status": { "label": "Identified", "isFinal": false, "isScheduled": false },
    "severity": { "label": "Degraded Performance", "description": "Some functionality is impaired.", "icon": "alert-triangle", "color": "#f59e0b" },
    "affectedComponents": {
      "6b0d3a8c-5e2f-4b7d-9c1e-f23456789abc": {
        "name": "API Gateway",
        "status": { "label": "Degraded Performance", "description": "Some functionality is impaired.", "icon": "alert-triangle", "color": "#f59e0b" }
      }
    },
    "startTime": "2026-04-25T09:45:00.000Z",
    "publish": true,
    "notifications": true,
    "timeline": [
      {
        "statusId": "7a3f9d2e-1b4c-4e8a-90b2-c3d4e5f67890",
        "timestamp": "2026-04-25T09:45:00.000Z",
        "status": { "label": "Investigating", "description": "We are looking into the issue.", "color": "#D97706", "icon": "search" },
        "message": "We are aware of elevated API response times and are investigating.",
        "author": "user@example.com",
        "isEdited": false
      },
      {
        "statusId": "9d1a4f7b-2c5e-4f8b-a1c3-d4e5f6789012",
        "timestamp": "2026-04-25T10:20:00.000Z",
        "status": { "label": "Identified", "description": "Root cause has been identified.", "color": "#f97316", "icon": "alert-circle" },
        "message": "Root cause identified as a misconfigured load balancer rule. Fix is being deployed.",
        "author": "user@example.com",
        "isEdited": false
      }
    ],
    "notes": [],
    "createdAt": "2026-04-25T09:58:00.000Z",
    "updatedAt": "2026-04-25T10:20:00.000Z"
  },
  "message": "Status update added successfully"
}
```

> **Incident end times and resolve time:** When the status matches a final workflow phase (e.g. "Resolved"), two timestamps are set.
>   **`endTime`** is set to the timeline entry's `timestamp`. A custom (backdated) `timestamp` updates `endTime` to that value — not the clock time when you submitted the request. This is the interval end used for uptime and calendar-day views.
>   **`resolvedAt`** is set once when the event first becomes final (typically the time of this request). It is not rewritten to a custom `timestamp`, and it is cleared if you reopen the incident later.
>   `endTime` and `resolvedAt` can therefore differ when you backdate the final timeline entry. Public [Event History](/docs/status-dashboards/content/event-history) orders and filters by when the event was marked final (`resolvedAt`), not by `endTime`.

> When the event's 
>   `notifications`
>    field is 
>   `true`
>   , a new timeline entry may enqueue subscriber notifications asynchronously. See 
>   [Event notifications](/docs/events/notifications)
>   .

> **Resolved incidents:**
>    Once an incident is resolved, you cannot add a non-final status via this endpoint. Use 
>   [`POST /app/events/{id}/reopen`](/docs/api/event-management/events/reopen)
>    instead. Maintenance events may still be updated via timeline when completed.

***

## Error responses
| Status | When                                                                                                                                                                               |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Validation error — invalid status label, message too long, timestamp in the future, event type does not support timelines, or a resolved incident must be re-opened via `/reopen`. |
| `403`  | Insufficient permissions.                                                                                                                                                          |
| `404`  | Event not found.                                                                                                                                                                   |