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

# 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`: false
- `destructiveHint`: true
- `idempotentHint`: true
- `openWorldHint`: 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: <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._:-]+$ ` |
| ` 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.

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

```json
{
  "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_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`.
- `insufficient_scope`: The connection does not include the permission this tool needs. `required_scopes` lists it.
- `not_found`: No record with that id exists for this account.
- `conflict`: The record changed since it was read: `expected_status` or `expected_revision` is stale. Nothing changed.
- `idempotency_key_reused`: The `idempotency_key` was 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](/developers/errors), [limits](/developers/limits), and [safe retries](/developers/idempotency).
