Contract 1.7.0 · Local previewRead Markdown

list_occurrences

Lists Occurrences (single scheduled instances of a Behavior, such as one day’s habit check-in) over a date range of up to 92 days, filtered by status or Behavior. Use it for history questions or to find an Occurrence id. Results are ordered by date and time.

Permission and annotations

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

  • title: “List Occurrences”
  • 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 yes string First local date, inclusive.; format: date
end_local_date yes string Last local date, inclusive.; format: date
statuses no array Only these stored statuses.; minItems: 1; maxItems: 3; uniqueItems: true
statuses[] yes string Values: unresolved, completed, not_completed
needs_decision_only no boolean Only Unresolved Occurrences before today.; default: false
behavior_ids no array Only these Behaviors.; minItems: 1; maxItems: 50; uniqueItems: true
behavior_ids[] yes string format: uuid
updated_since no string Return only records changed at or after this instant. Use it for incremental reads.; format: date-time
page_size no integer Items per page.; minimum: 1; maximum: 100; default: 50
cursor no string Opaque next_cursor from the previous page.; minLength: 1; maxLength: 512; pattern: ^[A-Za-z0-9_-]+$

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_+\-/]+$
occurrences yes array
occurrences[] yes object An Occurrence: one scheduled instance of a Behavior on one local date.
occurrences[].id yes string format: uuid
occurrences[].behavior_id yes string format: uuid
occurrences[].behavior_title yes string
occurrences[].category_name yes string or null
occurrences[].local_date yes string Calendar date (YYYY-MM-DD) in the account timezone.; format: date
occurrences[].timezone yes string IANA timezone name.; minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_+\-/]+$
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]$
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]$
occurrences[].move yes object or null Set while a per-day move places the Occurrence away from its planned time. Null otherwise.
occurrences[].move.planned_start_at yes string The planned start. It does not change when the item moves.; format: date-time; pattern: [Zz]$
occurrences[].move.start_at yes string The moved start.; format: date-time; pattern: [Zz]$
occurrences[].move.end_at yes string The moved end. A move keeps the item’s length.; format: date-time; pattern: [Zz]$
occurrences[].schedule yes object
occurrences[].schedule.kind yes string Values: exact, range
occurrences[].schedule.preset yes string or null Values: morning, afternoon, evening, night, null
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]$
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]$
occurrences[].schedule.label yes string
occurrences[].status yes string Stored status.; Values: unresolved, completed, not_completed
occurrences[].status_label yes string Values: Unresolved, Completed, Not Completed
occurrences[].needs_decision yes boolean Derived: true when the status is unresolved and local_date is before today. Never stored.
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
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
occurrences[].completed_at yes string or null format: date-time; pattern: [Zz]$
occurrences[].status_marked_at yes string or null format: date-time; pattern: [Zz]$
occurrences[].note yes string or null
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
occurrences[].parent_title no string or null Parent Behavior title when the Occurrence belongs to a sub-behavior, otherwise null.
occurrences[].updated_at yes string format: date-time; pattern: [Zz]$
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._:-]+$
next_cursor yes string or null Cursor for the next page, or null when this is the last page.; minLength: 1; maxLength: 512; pattern: ^[A-Za-z0-9_-]+$
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": "list_occurrences",
  "arguments": {
    "start_local_date": "2026-08-01",
    "end_local_date": "2026-10-31",
    "statuses": [
      "unresolved",
      "not_completed"
    ],
    "behavior_ids": [
      "00000001-1111-4111-8111-000000000001"
    ],
    "page_size": 25
  }
}

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",
  "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"
    },
    {
      "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"
    }
  ],
  "next_cursor": "eyJvIjoyfQ",
  "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.
  • limit_exceeded: The request asks for more than a contract limit allows, such as too long a date range or too large a result. Narrow the request.

Output size limits can also return limit_exceeded. See error handling, limits, and safe retries.