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

# 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: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` 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: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` 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.

```json
{
  "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.

```json
{
  "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](/developers/errors), [limits](/developers/limits), and [safe retries](/developers/idempotency).
