---
title: "get_timeline"
description: "Get Timeline: inputs, outputs, permissions, examples, and errors."
canonical_url: https://cadence-me.com/developers/tools/get_timeline
last_updated: 2026-10-18
status: stable
source: src/data/developer-reference.json
---

# get_timeline

Returns the Timeline as the Cadence web app groups it: Needs decision (Unresolved Occurrences from before today) plus each day's Occurrences, with parent Behavior slots and their derived progress in `parent_groups`. Use it for questions such as "what's on today" or "what still needs a decision". Covers up to 14 days from the start date.

## Permission and annotations

Required scope: `cadence.read`. Contract 1.7.0; available since 1.0.0.

- `title`: "Get Timeline"
- `readOnlyHint`: true
- `destructiveHint`: false
- `idempotentHint`: true
- `openWorldHint`: false

Reads account data and changes nothing, so readOnlyHint is true. Claude runs read-only tools without per-call confirmation, and OpenAI asks for readOnlyHint on every read. openWorldHint is false because the tool reaches only the user's own Cadence account.

## Input

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` start_local_date ` | no | string | First day to return. Defaults to today in the account timezone.; format: ` date ` |
| ` days ` | no | integer | Number of days to return.; minimum: ` 1 `; maximum: ` 14 `; default: ` 1 ` |
| ` include_needs_decision ` | no | boolean | Include the Needs decision group.; default: ` true ` |

## Output

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` timezone ` | yes | string | IANA timezone name.; minLength: ` 1 `; maxLength: ` 64 `; pattern: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` today_local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` needs_decision ` | yes | object or null | Null when include_needs_decision is false. |
| ` needs_decision.occurrences ` | yes | array | maxItems: ` 100 ` |
| ` needs_decision.occurrences[] ` | yes | object | An Occurrence: one scheduled instance of a Behavior on one local date. |
| ` needs_decision.occurrences[].id ` | yes | string | format: ` uuid ` |
| ` needs_decision.occurrences[].behavior_id ` | yes | string | format: ` uuid ` |
| ` needs_decision.occurrences[].behavior_title ` | yes | string |  |
| ` needs_decision.occurrences[].category_name ` | yes | string or null |  |
| ` needs_decision.occurrences[].local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` needs_decision.occurrences[].timezone ` | yes | string | IANA timezone name.; minLength: ` 1 `; maxLength: ` 64 `; pattern: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` needs_decision.occurrences[].scheduled_for ` | yes | string | Planned start as a UTC instant. It never changes when the Occurrence is moved for the day.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` needs_decision.occurrences[].effective_start_at ` | yes | string | Where the Occurrence sits today: its moved start when `move` is set, otherwise the planned start. Show, remind and match by this time.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` needs_decision.occurrences[].move ` | yes | object or null | Set while a per-day move places the Occurrence away from its planned time. Null otherwise. |
| ` needs_decision.occurrences[].move.planned_start_at ` | yes | string | The planned start. It does not change when the item moves.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` needs_decision.occurrences[].move.start_at ` | yes | string | The moved start.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` needs_decision.occurrences[].move.end_at ` | yes | string | The moved end. A move keeps the item's length.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` needs_decision.occurrences[].schedule ` | yes | object |  |
| ` needs_decision.occurrences[].schedule.kind ` | yes | string | Values: ` exact `, ` range ` |
| ` needs_decision.occurrences[].schedule.preset ` | yes | string or null | Values: ` morning `, ` afternoon `, ` evening `, ` night `, ` null ` |
| ` needs_decision.occurrences[].schedule.start_time ` | yes | string | Local wall-clock time, 24-hour HH:MM.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` needs_decision.occurrences[].schedule.end_time ` | yes | string or null | Local wall-clock time, 24-hour HH:MM.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` needs_decision.occurrences[].schedule.label ` | yes | string |  |
| ` needs_decision.occurrences[].status ` | yes | string | Stored status.; Values: ` unresolved `, ` completed `, ` not_completed ` |
| ` needs_decision.occurrences[].status_label ` | yes | string | Values: ` Unresolved `, ` Completed `, ` Not Completed ` |
| ` needs_decision.occurrences[].needs_decision ` | yes | boolean | Derived: true when the status is unresolved and local_date is before today. Never stored. |
| ` needs_decision.occurrences[].origin ` | yes | string | scheduled comes from the Behavior's schedule; opportunity was added to its day from the person's opportunities (contract 1.6.0).; Values: ` scheduled `, ` opportunity ` |
| ` needs_decision.occurrences[].added_by ` | yes | string or null | Who added an opportunity Occurrence: user, daily_brief, chat or mcp. Null for scheduled Occurrences.; Values: ` user `, ` daily_brief `, ` chat `, ` mcp `, ` null ` |
| ` needs_decision.occurrences[].completed_at ` | yes | string or null | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` needs_decision.occurrences[].status_marked_at ` | yes | string or null | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` needs_decision.occurrences[].note ` | yes | string or null |  |
| ` needs_decision.occurrences[].parent_behavior_id ` | no | string or null | Parent Behavior id when the Occurrence belongs to a sub-behavior, otherwise null. Present on reads and on set_parent_occurrence_status (contract 1.7.0).; format: ` uuid ` |
| ` needs_decision.occurrences[].parent_title ` | no | string or null | Parent Behavior title when the Occurrence belongs to a sub-behavior, otherwise null. |
| ` needs_decision.occurrences[].updated_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` needs_decision.occurrences[].revision ` | yes | string | Opaque version token of this record. Send it back as `expected_revision` to avoid overwriting a newer change.; minLength: ` 1 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9._:-]+$ ` |
| ` needs_decision.total_count ` | yes | integer | minimum: ` 0 ` |
| ` needs_decision.truncated ` | yes | boolean | True when more Needs decision Occurrences exist than are returned. |
| ` needs_decision.lookback_start_local_date ` | yes | string | Earliest date searched (90 days back). Use list_occurrences for older history.; format: ` date ` |
| ` needs_decision.parent_groups ` | no | array | Parent Behavior slots with a Needs decision Occurrence (contract 1.7.0). |
| ` needs_decision.parent_groups[] ` | yes | object | A parent Behavior's slot: its sub-behaviors' Occurrences at one time on one day, with a derived rollup. |
| ` needs_decision.parent_groups[].parent_behavior_id ` | yes | string | format: ` uuid ` |
| ` needs_decision.parent_groups[].title ` | yes | string | Parent Behavior title. |
| ` needs_decision.parent_groups[].local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` needs_decision.parent_groups[].slot_key ` | yes | string | Start of the slot: the earliest effective start among its Occurrences. Send it to set_parent_occurrence_status.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` needs_decision.parent_groups[].scheduled_time_label ` | yes | string | Display time, for example `7:30 AM` or `Morning`. |
| ` needs_decision.parent_groups[].derived_status ` | yes | string | Derived and never stored: the shared status when every Occurrence has it, otherwise partial.; Values: ` unresolved `, ` completed `, ` not_completed `, ` partial ` |
| ` needs_decision.parent_groups[].progress_label ` | yes | string | Completed over scheduled, for example `2/3`. |
| ` needs_decision.parent_groups[].completed_count ` | yes | integer | minimum: ` 0 ` |
| ` needs_decision.parent_groups[].not_completed_count ` | yes | integer | minimum: ` 0 ` |
| ` needs_decision.parent_groups[].unresolved_count ` | yes | integer | minimum: ` 0 ` |
| ` needs_decision.parent_groups[].total_count ` | yes | integer | minimum: ` 1 ` |
| ` needs_decision.parent_groups[].needs_decision ` | yes | boolean | Derived: true when an Occurrence in the slot is Unresolved and before today. |
| ` needs_decision.parent_groups[].occurrence_ids ` | yes | array | The sub-behavior Occurrences in this slot, in sub-behavior order.; minItems: ` 1 ` |
| ` needs_decision.parent_groups[].occurrence_ids[] ` | yes | string | format: ` uuid ` |
| ` days ` | yes | array | maxItems: ` 14 ` |
| ` days[] ` | yes | object |  |
| ` days[].local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` days[].is_today ` | yes | boolean |  |
| ` days[].day_note ` | no | string or null | The user's day note for this date, or null. Separate from Occurrence notes and statuses. |
| ` days[].occurrences ` | yes | array | Every Occurrence of the day, sub-behavior Occurrences included. |
| ` days[].occurrences[] ` | yes | object | An Occurrence: one scheduled instance of a Behavior on one local date. |
| ` days[].occurrences[].id ` | yes | string | format: ` uuid ` |
| ` days[].occurrences[].behavior_id ` | yes | string | format: ` uuid ` |
| ` days[].occurrences[].behavior_title ` | yes | string |  |
| ` days[].occurrences[].category_name ` | yes | string or null |  |
| ` days[].occurrences[].local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` days[].occurrences[].timezone ` | yes | string | IANA timezone name.; minLength: ` 1 `; maxLength: ` 64 `; pattern: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` days[].occurrences[].scheduled_for ` | yes | string | Planned start as a UTC instant. It never changes when the Occurrence is moved for the day.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` days[].occurrences[].effective_start_at ` | yes | string | Where the Occurrence sits today: its moved start when `move` is set, otherwise the planned start. Show, remind and match by this time.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` days[].occurrences[].move ` | yes | object or null | Set while a per-day move places the Occurrence away from its planned time. Null otherwise. |
| ` days[].occurrences[].move.planned_start_at ` | yes | string | The planned start. It does not change when the item moves.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` days[].occurrences[].move.start_at ` | yes | string | The moved start.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` days[].occurrences[].move.end_at ` | yes | string | The moved end. A move keeps the item's length.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` days[].occurrences[].schedule ` | yes | object |  |
| ` days[].occurrences[].schedule.kind ` | yes | string | Values: ` exact `, ` range ` |
| ` days[].occurrences[].schedule.preset ` | yes | string or null | Values: ` morning `, ` afternoon `, ` evening `, ` night `, ` null ` |
| ` days[].occurrences[].schedule.start_time ` | yes | string | Local wall-clock time, 24-hour HH:MM.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` days[].occurrences[].schedule.end_time ` | yes | string or null | Local wall-clock time, 24-hour HH:MM.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` days[].occurrences[].schedule.label ` | yes | string |  |
| ` days[].occurrences[].status ` | yes | string | Stored status.; Values: ` unresolved `, ` completed `, ` not_completed ` |
| ` days[].occurrences[].status_label ` | yes | string | Values: ` Unresolved `, ` Completed `, ` Not Completed ` |
| ` days[].occurrences[].needs_decision ` | yes | boolean | Derived: true when the status is unresolved and local_date is before today. Never stored. |
| ` days[].occurrences[].origin ` | yes | string | scheduled comes from the Behavior's schedule; opportunity was added to its day from the person's opportunities (contract 1.6.0).; Values: ` scheduled `, ` opportunity ` |
| ` days[].occurrences[].added_by ` | yes | string or null | Who added an opportunity Occurrence: user, daily_brief, chat or mcp. Null for scheduled Occurrences.; Values: ` user `, ` daily_brief `, ` chat `, ` mcp `, ` null ` |
| ` days[].occurrences[].completed_at ` | yes | string or null | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` days[].occurrences[].status_marked_at ` | yes | string or null | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` days[].occurrences[].note ` | yes | string or null |  |
| ` days[].occurrences[].parent_behavior_id ` | no | string or null | Parent Behavior id when the Occurrence belongs to a sub-behavior, otherwise null. Present on reads and on set_parent_occurrence_status (contract 1.7.0).; format: ` uuid ` |
| ` days[].occurrences[].parent_title ` | no | string or null | Parent Behavior title when the Occurrence belongs to a sub-behavior, otherwise null. |
| ` days[].occurrences[].updated_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` days[].occurrences[].revision ` | yes | string | Opaque version token of this record. Send it back as `expected_revision` to avoid overwriting a newer change.; minLength: ` 1 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9._:-]+$ ` |
| ` days[].parent_groups ` | no | array | The day's parent Behavior slots in time order. Their Occurrences also appear in `occurrences` (contract 1.7.0). |
| ` days[].parent_groups[] ` | yes | object | A parent Behavior's slot: its sub-behaviors' Occurrences at one time on one day, with a derived rollup. |
| ` days[].parent_groups[].parent_behavior_id ` | yes | string | format: ` uuid ` |
| ` days[].parent_groups[].title ` | yes | string | Parent Behavior title. |
| ` days[].parent_groups[].local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` days[].parent_groups[].slot_key ` | yes | string | Start of the slot: the earliest effective start among its Occurrences. Send it to set_parent_occurrence_status.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` days[].parent_groups[].scheduled_time_label ` | yes | string | Display time, for example `7:30 AM` or `Morning`. |
| ` days[].parent_groups[].derived_status ` | yes | string | Derived and never stored: the shared status when every Occurrence has it, otherwise partial.; Values: ` unresolved `, ` completed `, ` not_completed `, ` partial ` |
| ` days[].parent_groups[].progress_label ` | yes | string | Completed over scheduled, for example `2/3`. |
| ` days[].parent_groups[].completed_count ` | yes | integer | minimum: ` 0 ` |
| ` days[].parent_groups[].not_completed_count ` | yes | integer | minimum: ` 0 ` |
| ` days[].parent_groups[].unresolved_count ` | yes | integer | minimum: ` 0 ` |
| ` days[].parent_groups[].total_count ` | yes | integer | minimum: ` 1 ` |
| ` days[].parent_groups[].needs_decision ` | yes | boolean | Derived: true when an Occurrence in the slot is Unresolved and before today. |
| ` days[].parent_groups[].occurrence_ids ` | yes | array | The sub-behavior Occurrences in this slot, in sub-behavior order.; minItems: ` 1 ` |
| ` days[].parent_groups[].occurrence_ids[] ` | yes | string | format: ` uuid ` |
| ` freshness ` | yes | object |  |
| ` freshness.as_of ` | yes | string | When Cadence read this data.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` freshness.occurrences_generated_through ` | yes | string or null | Last local date for which Occurrences exist. Later dates have none yet.; format: ` date ` |

## Example call

Synthetic contract fixture. Replace identifiers and dates with records returned for your account. This is the SDK tools/call payload, not a complete HTTP request.

```json
{
  "name": "get_timeline",
  "arguments": {}
}
```

## Example result

Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.

```json
{
  "timezone": "America/New_York",
  "today_local_date": "2026-10-18",
  "needs_decision": {
    "occurrences": [
      {
        "id": "00000004-1111-4111-8111-000000000004",
        "behavior_id": "00000001-1111-4111-8111-000000000001",
        "behavior_title": "Morning walk",
        "category_name": "Fitness",
        "local_date": "2026-10-16",
        "timezone": "America/New_York",
        "scheduled_for": "2026-10-16T11:30:00Z",
        "effective_start_at": "2026-10-16T11:30:00Z",
        "move": null,
        "schedule": {
          "kind": "exact",
          "preset": null,
          "start_time": "07:30",
          "end_time": null,
          "label": "7:30 AM"
        },
        "status": "unresolved",
        "status_label": "Unresolved",
        "needs_decision": true,
        "origin": "scheduled",
        "added_by": null,
        "completed_at": null,
        "status_marked_at": null,
        "note": null,
        "updated_at": "2026-10-18T13:00:00Z",
        "revision": "o1.3"
      }
    ],
    "total_count": 1,
    "truncated": false,
    "lookback_start_local_date": "2026-07-20"
  },
  "days": [
    {
      "local_date": "2026-10-18",
      "is_today": true,
      "occurrences": [
        {
          "id": "00000005-1111-4111-8111-000000000005",
          "behavior_id": "00000001-1111-4111-8111-000000000001",
          "behavior_title": "Morning walk",
          "category_name": "Fitness",
          "local_date": "2026-10-18",
          "timezone": "America/New_York",
          "scheduled_for": "2026-10-18T11:30:00Z",
          "effective_start_at": "2026-10-18T11:30:00Z",
          "move": null,
          "schedule": {
            "kind": "exact",
            "preset": null,
            "start_time": "07:30",
            "end_time": null,
            "label": "7:30 AM"
          },
          "status": "completed",
          "status_label": "Completed",
          "needs_decision": false,
          "origin": "scheduled",
          "added_by": null,
          "completed_at": "2026-10-18T11:41:00Z",
          "status_marked_at": "2026-10-18T11:41:00Z",
          "note": "Felt good.\nCold out.",
          "updated_at": "2026-10-18T13:00:00Z",
          "revision": "o1.3"
        }
      ]
    }
  ],
  "freshness": {
    "as_of": "2026-10-18T15:56:42Z",
    "occurrences_generated_through": "2026-11-17"
  }
}
```

## Errors

- `invalid_input`: The input does not match the tool's schema or rules. `field_errors` names each problem.
- `authentication_required`: The access token is missing, expired, revoked, or issued for another resource. Reconnect Cadence.
- `rate_limited`: Too many requests for this connection. Retry after `retry_after_seconds`.
- `service_unavailable`: Cadence integrations are temporarily unavailable.
- `internal_error`: Cadence could not complete the request. Nothing is assumed to have changed; retry once with the same `idempotency_key`.

Output size limits can also return `limit_exceeded`. See [error handling](/developers/errors), [limits](/developers/limits), and [safe retries](/developers/idempotency).
