Contract 1.7.0 · Local previewRead Markdown

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: ^[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_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, limits, and safe retries.