set_occurrence_status
Marks one Occurrence Completed or Not Completed, or returns it to Unresolved. Use it when the user says they did, or did not do, a scheduled habit, routine, or task. Setting the current status again changes nothing. Each change is kept in the status history.
Permission and annotations
Required scope: cadence.occurrences.write. Contract 1.7.0; available since 1.0.0.
title: “Set Occurrence status”readOnlyHint: falsedestructiveHint: trueidempotentHint: trueopenWorldHint: false
Changes stored data, so readOnlyHint is false. Claude’s review criteria ask for destructiveHint true on tools that modify data, so Claude confirms each call; OpenAI reserves it for hard-to-reverse outcomes, and a status can be set back, so the hint is conservative for ChatGPT. The same arguments always produce the same end state, so idempotentHint is true. openWorldHint is false: only the user’s own Cadence account is touched.
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 |
status |
yes | string | New status.; Values: unresolved, completed, not_completed |
expected_status |
no | string | Status the client last read. If the stored status differs, the call fails with conflict and changes nothing.; Values: unresolved, completed, not_completed |
idempotency_key |
no | string | Optional client-chosen key. Repeating a call with the same key and input within 24 hours returns the first result and changes nothing.; minLength: 8; maxLength: 128; 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 |
|---|---|---|---|
occurrence |
yes | object | An Occurrence: one scheduled instance of a Behavior on one local date. |
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: ^[A-Za-z0-9_+\-/]+$ |
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._:-]+$ |
previous_status |
yes | string | Values: unresolved, completed, not_completed |
changed |
yes | boolean | False when the Occurrence already had this status. |
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": "set_occurrence_status",
"arguments": {
"occurrence_id": "00000004-1111-4111-8111-000000000004",
"status": "completed",
"expected_status": "unresolved",
"idempotency_key": "claude-7f3a-0001"
}
}
Example result
Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.
{
"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"
},
"previous_status": "unresolved",
"changed": true
}
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.insufficient_scope: The connection does not include the permission this tool needs.required_scopeslists it.not_found: No record with that id exists for this account.conflict: The record changed since it was read:expected_statusorexpected_revisionis stale. Nothing changed.idempotency_key_reused: Theidempotency_keywas already used with a different input. Use a new key for a new request.invalid_state: The record’s current state does not allow this change.
Output size limits can also return limit_exceeded. See error handling, limits, and safe retries.