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: truedestructiveHint: falseidempotentHint: trueopenWorldHint: 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: ^[A-Za-z0-9_+\-/]+$ |
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: ^[A-Za-z0-9_+\-/]+$ |
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: ^[A-Za-z0-9_+\-/]+$ |
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.
{
"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.
{
"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_errorsnames 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 afterretry_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 sameidempotency_key.
Output size limits can also return limit_exceeded. See error handling, limits, and safe retries.