set_parent_occurrence_status
Marks every sub-behavior Occurrence in one parent Behavior slot Completed or Not Completed in one change, such as a whole skin routine one morning. Name the slot with local_date, plus slot_key from get_timeline parent_groups when the parent has several times that day, or list occurrence_ids. Occurrences that already have the status do not change. To mark one step, use set_occurrence_status.
Permission and annotations
Required scope: cadence.occurrences.write. Contract 1.7.0; available since 1.7.0.
title: “Set parent Behavior slot status”readOnlyHint: falsedestructiveHint: trueidempotentHint: trueopenWorldHint: false
Changes stored statuses of several Occurrences at once, so readOnlyHint is false and destructiveHint is true under Claude’s review criteria, which ask for it on tools that modify data; each status can be set back, so the hint is conservative for ChatGPT. The same arguments always leave the same statuses, 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 |
|---|---|---|---|
parent_behavior_id |
yes | string | Behavior id.; format: uuid |
status |
yes | string | New status for each sub-behavior Occurrence in the slot.; Values: completed, not_completed |
local_date |
no | string | Day of the slot, in the account timezone.; format: date |
slot_key |
no | string | slot_key of one parent group from get_timeline. Needs local_date.; format: date-time |
occurrence_ids |
no | array | The sub-behavior Occurrences to mark. All must belong to sub-behaviors of this parent on one day.; minItems: 1; maxItems: 50; uniqueItems: true |
occurrence_ids[] |
yes | string | format: uuid |
expected_statuses |
no | array | Statuses the client last read. If any stored status differs, the call fails with conflict and changes nothing.; minItems: 1; maxItems: 50 |
expected_statuses[] |
yes | object | |
expected_statuses[].occurrence_id |
yes | string | Occurrence id.; format: uuid |
expected_statuses[].status |
yes | string | Status the client last read.; 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._:-]+$ |
Provide at least one of: local_date, occurrence_ids.
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 |
|---|---|---|---|
parent_behavior_id |
yes | string | format: uuid |
status |
yes | string | New status for each sub-behavior Occurrence in the slot.; Values: completed, not_completed |
occurrences |
yes | array | The marked Occurrences after the change, in sub-behavior order.; maxItems: 50 |
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._:-]+$ |
changed_occurrence_ids |
yes | array | Occurrences whose status changed. Empty when all already had the status. |
changed_occurrence_ids[] |
yes | string | format: uuid |
parent_groups |
yes | array | The derived rollup of each slot the marked Occurrences belong to. |
parent_groups[] |
yes | object | A parent Behavior’s slot: its sub-behaviors’ Occurrences at one time on one day, with a derived rollup. |
parent_groups[].parent_behavior_id |
yes | string | format: uuid |
parent_groups[].title |
yes | string | Parent Behavior title. |
parent_groups[].local_date |
yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: date |
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]$ |
parent_groups[].scheduled_time_label |
yes | string | Display time, for example 7:30 AM or Morning. |
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 |
parent_groups[].progress_label |
yes | string | Completed over scheduled, for example 2/3. |
parent_groups[].completed_count |
yes | integer | minimum: 0 |
parent_groups[].not_completed_count |
yes | integer | minimum: 0 |
parent_groups[].unresolved_count |
yes | integer | minimum: 0 |
parent_groups[].total_count |
yes | integer | minimum: 1 |
parent_groups[].needs_decision |
yes | boolean | Derived: true when an Occurrence in the slot is Unresolved and before today. |
parent_groups[].occurrence_ids |
yes | array | The sub-behavior Occurrences in this slot, in sub-behavior order.; minItems: 1 |
parent_groups[].occurrence_ids[] |
yes | string | format: uuid |
changed |
yes | boolean | False when every 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_parent_occurrence_status",
"arguments": {
"parent_behavior_id": "00000009-1111-4111-8111-000000000009",
"local_date": "2026-10-18",
"status": "completed",
"idempotency_key": "routine-mark-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.
{
"parent_behavior_id": "00000009-1111-4111-8111-000000000009",
"status": "completed",
"occurrences": [
{
"id": "0000000c-1111-4111-8111-00000000000c",
"behavior_id": "0000000a-1111-4111-8111-00000000000a",
"behavior_title": "Cleanser",
"category_name": "Fitness",
"local_date": "2026-10-18",
"timezone": "America/New_York",
"scheduled_for": "2026-10-18T11:00:00Z",
"effective_start_at": "2026-10-18T11:00:00Z",
"move": null,
"schedule": {
"kind": "exact",
"preset": null,
"start_time": "07:00",
"end_time": null,
"label": "7:00 AM"
},
"status": "completed",
"origin": "scheduled",
"added_by": null,
"status_label": "Completed",
"needs_decision": false,
"completed_at": "2026-10-18T11:05:00Z",
"status_marked_at": "2026-10-18T11:05:00Z",
"note": "Felt good.\nCold out.",
"updated_at": "2026-10-18T13:00:00Z",
"revision": "o1.3",
"parent_behavior_id": "00000009-1111-4111-8111-000000000009",
"parent_title": "Skin routine"
},
{
"id": "0000000d-1111-4111-8111-00000000000d",
"behavior_id": "0000000b-1111-4111-8111-00000000000b",
"behavior_title": "Retinol",
"category_name": "Fitness",
"local_date": "2026-10-18",
"timezone": "America/New_York",
"scheduled_for": "2026-10-18T11:00:00Z",
"effective_start_at": "2026-10-18T11:00:00Z",
"move": null,
"schedule": {
"kind": "exact",
"preset": null,
"start_time": "07:00",
"end_time": null,
"label": "7:00 AM"
},
"status": "completed",
"origin": "scheduled",
"added_by": null,
"status_label": "Completed",
"needs_decision": false,
"completed_at": "2026-10-18T11:05:00Z",
"status_marked_at": "2026-10-18T11:05:00Z",
"note": "Felt good.\nCold out.",
"updated_at": "2026-10-18T13:00:00Z",
"revision": "o1.3",
"parent_behavior_id": "00000009-1111-4111-8111-000000000009",
"parent_title": "Skin routine"
}
],
"changed_occurrence_ids": [
"0000000d-1111-4111-8111-00000000000d"
],
"parent_groups": [
{
"parent_behavior_id": "00000009-1111-4111-8111-000000000009",
"title": "Skin routine",
"local_date": "2026-10-18",
"slot_key": "2026-10-18T11:00:00Z",
"scheduled_time_label": "7:00 AM",
"derived_status": "completed",
"progress_label": "2/2",
"completed_count": 2,
"not_completed_count": 0,
"unresolved_count": 0,
"total_count": 2,
"needs_decision": false,
"occurrence_ids": [
"0000000c-1111-4111-8111-00000000000c",
"0000000d-1111-4111-8111-00000000000d"
]
}
],
"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.