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

# get_occurrence

Returns one Occurrence with its note, full status history, measured time sessions, and revision. Use it before changing an Occurrence's status or note.

## Permission and annotations

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

- `title`: "Get Occurrence"
- `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 |
|---|---|---|---|
| ` occurrence_id ` | yes | string | Occurrence id.; format: ` uuid ` |

## 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 |
|---|---|---|---|
| ` occurrence ` | yes | object | One Occurrence with its note, status history, and measured time sessions. |
| ` occurrence.id ` | yes | string | format: ` uuid ` |
| ` occurrence.behavior_id ` | yes | string | format: ` uuid ` |
| ` occurrence.behavior_title ` | yes | string |  |
| ` occurrence.category_name ` | yes | string or null |  |
| ` occurrence.local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` occurrence.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> |
| ` occurrence.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]$ ` |
| ` occurrence.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]$ ` |
| ` occurrence.move ` | yes | object or null | Set while a per-day move places the Occurrence away from its planned time. Null otherwise. |
| ` occurrence.move.planned_start_at ` | yes | string | The planned start. It does not change when the item moves.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.move.start_at ` | yes | string | The moved start.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.move.end_at ` | yes | string | The moved end. A move keeps the item's length.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.schedule ` | yes | object |  |
| ` occurrence.schedule.kind ` | yes | string | Values: ` exact `, ` range ` |
| ` occurrence.schedule.preset ` | yes | string or null | Values: ` morning `, ` afternoon `, ` evening `, ` night `, ` null ` |
| ` occurrence.schedule.start_time ` | yes | string | Local wall-clock time, 24-hour HH:MM.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` occurrence.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]$ ` |
| ` occurrence.schedule.label ` | yes | string |  |
| ` occurrence.status ` | yes | string | Stored status.; Values: ` unresolved `, ` completed `, ` not_completed ` |
| ` occurrence.status_label ` | yes | string | Values: ` Unresolved `, ` Completed `, ` Not Completed ` |
| ` occurrence.needs_decision ` | yes | boolean | Derived: true when the status is unresolved and local_date is before today. Never stored. |
| ` occurrence.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 ` |
| ` occurrence.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 ` |
| ` occurrence.completed_at ` | yes | string or null | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.status_marked_at ` | yes | string or null | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.note ` | yes | string or null |  |
| ` occurrence.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 ` |
| ` occurrence.parent_title ` | no | string or null | Parent Behavior title when the Occurrence belongs to a sub-behavior, otherwise null. |
| ` occurrence.updated_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.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._:-]+$ ` |
| ` occurrence.status_history ` | yes | array | Append-only status changes, oldest first. |
| ` occurrence.status_history[] ` | yes | object |  |
| ` occurrence.status_history[].id ` | yes | string | format: ` uuid ` |
| ` occurrence.status_history[].previous_status ` | yes | string or null | Values: ` unresolved `, ` completed `, ` not_completed `, ` null ` |
| ` occurrence.status_history[].status ` | yes | string | Values: ` unresolved `, ` completed `, ` not_completed ` |
| ` occurrence.status_history[].semantics ` | yes | string | Values: ` explicit_user_mark `, ` explicit_user_correction `, ` imported_explicit `, ` system_rule_declared `, ` ambiguous_import ` |
| ` occurrence.status_history[].capture_method ` | yes | string | Values: ` manual_tap `, ` manual_text `, ` system_generated `, ` imported `, ` inferred `, ` derived `, ` ai_generated `, ` unknown ` |
| ` occurrence.status_history[].recorded_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.status_history[].effective_at ` | yes | string or null | When it really happened. For Completed it can be earlier than recorded_at when the person said when they did it (contract 1.4.0).; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.status_history[].not_done_reason ` | yes | string or null | The optional one-tap reason the person gave on a Not Completed mark. Null otherwise (contract 1.4.0).; Values: ` no_time `, ` forgot `, ` low_energy `, ` away `, ` chose_not_to `, ` null ` |
| ` occurrence.status_history[].local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` occurrence.status_history[].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> |
| ` occurrence.time_sessions ` | yes | array |  |
| ` occurrence.time_sessions[] ` | yes | object |  |
| ` occurrence.time_sessions[].id ` | yes | string | format: ` uuid ` |
| ` occurrence.time_sessions[].started_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.time_sessions[].stopped_at ` | yes | string or null | Null while the session is running.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` occurrence.time_sessions[].duration_seconds ` | yes | integer or null | Null while the session is running.; minimum: ` 0 ` |

## 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_occurrence",
  "arguments": {
    "occurrence_id": "00000005-1111-4111-8111-000000000005"
  }
}
```

## 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
{
  "occurrence": {
    "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",
    "status_history": [
      {
        "id": "0000000a-1111-4111-8111-00000000000a",
        "previous_status": "unresolved",
        "status": "not_completed",
        "semantics": "explicit_user_mark",
        "capture_method": "manual_tap",
        "recorded_at": "2026-10-18T11:35:00Z",
        "effective_at": "2026-10-18T11:35:00Z",
        "not_done_reason": null,
        "local_date": "2026-10-18",
        "timezone": "America/New_York"
      },
      {
        "id": "0000000b-1111-4111-8111-00000000000b",
        "previous_status": "not_completed",
        "status": "completed",
        "semantics": "explicit_user_correction",
        "capture_method": "manual_text",
        "recorded_at": "2026-10-18T11:41:00Z",
        "effective_at": "2026-10-18T11:41:00Z",
        "not_done_reason": null,
        "local_date": "2026-10-18",
        "timezone": "America/New_York"
      }
    ],
    "time_sessions": [
      {
        "id": "0000000c-1111-4111-8111-00000000000c",
        "started_at": "2026-10-18T11:20:00Z",
        "stopped_at": "2026-10-18T11:40:00Z",
        "duration_seconds": 1200
      }
    ]
  }
}
```

## 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`.
- `not_found`: No record with that id exists for this account.

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