Contract 1.7.0 · Local previewRead Markdown

list_behaviors

Lists the user’s Behaviors, the recurring things they track (habits, routines, or recurring tasks), with schedules, reminders, category, run state, archive notes, and sub-behavior links. A parent Behavior lists its sub-behaviors (one level deep). Use it to find a Behavior id or review what the user tracks. Includes archived Behaviors unless filtered.

Permission and annotations

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

  • title: “List Behaviors”
  • 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
state no string Which Behaviors to include. running is active and scheduling; not_running is active but ended or paused; active is both.; default: all; Values: active, archived, running, not_running, all
category_id no string Only Behaviors in this category.; format: uuid
is_opportunity no boolean true: only Behaviors available as opportunities; false: only the others. Omit for both (contract 1.6.0).
parent_behavior_id no string Only the sub-behaviors of this parent Behavior (contract 1.7.0).; format: uuid
hierarchy no string top_level returns parents and standalone Behaviors; sub_behaviors returns only sub-behaviors (contract 1.7.0).; default: all; Values: all, top_level, sub_behaviors
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
behaviors yes array
behaviors[] yes object A Behavior: a recurring thing the user tracks (a habit, routine, or recurring task).
behaviors[].id yes string format: uuid
behaviors[].title yes string
behaviors[].description yes string or null
behaviors[].location_text yes string or null
behaviors[].category yes object or null
behaviors[].category.id yes string format: uuid
behaviors[].category.name yes string
behaviors[].state yes string Archived Behaviors keep their history but schedule no new Occurrences.; Values: active, archived
behaviors[].archived_at yes string or null format: date-time; pattern: [Zz]$
behaviors[].auto_archived_at yes string or null Set on Behaviors that an end date archived automatically before Cadence stopped archiving on an end. New ends never set it.; format: date-time; pattern: [Zz]$
behaviors[].run_state yes string running schedules Occurrences; ended has passed its end and paused is inside a pause, both still active and shown under Not running; archived is archived.; Values: running, ended, paused, archived
behaviors[].is_opportunity yes boolean True when the Behavior is available as an opportunity: the person can add it to today when there is room, with or without a schedule (contract 1.6.0).
behaviors[].end_on yes string or null Last local day the Behavior runs. Null when it has no end.; format: date
behaviors[].end_time yes string or null Local time on end_on when it stops. Null means it stops at the end of that day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
behaviors[].pause yes object or null The current or upcoming pause. Null when none is set or the pause is over.
behaviors[].pause.from_on yes string First paused local day.; format: date
behaviors[].pause.from_time yes string or null Local time on from_on when the pause starts. Null means the start of that day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
behaviors[].pause.back_on yes string Local day the Behavior runs again by itself, from the start of the day.; format: date
behaviors[].end_date yes string or null Deprecated: read end_on. The day after end_on, kept for one minor version.; format: date
behaviors[].default_duration_minutes yes integer or null minimum: 1
behaviors[].timezone yes string IANA timezone name.; minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_+\-/]+$
behaviors[].schedules yes array
behaviors[].schedules[] yes object
behaviors[].schedules[].id yes string format: uuid
behaviors[].schedules[].recurrence yes one of several shapes Structured recurrence rule. Natural-language rules and cron syntax are not accepted.
behaviors[].schedules[].recurrence.frequency yes string Value: daily
behaviors[].schedules[].recurrence.interval yes integer Repeat every N days. 1 means every day.; minimum: 1
behaviors[].schedules[].recurrence.frequency yes string Value: interval_days
behaviors[].schedules[].recurrence.interval_days yes integer Repeat every N days counted from the start date.; minimum: 1
behaviors[].schedules[].recurrence.frequency yes string Value: weekly
behaviors[].schedules[].recurrence.interval yes integer Repeat every N weeks. 1 means every week.; minimum: 1
behaviors[].schedules[].recurrence.days_of_week yes array minItems: 1; maxItems: 7; uniqueItems: true
behaviors[].schedules[].recurrence.days_of_week[] yes string Values: monday, tuesday, wednesday, thursday, friday, saturday, sunday
behaviors[].schedules[].recurrence.frequency yes string Value: monthly
behaviors[].schedules[].recurrence.interval yes integer Repeat every N months.; minimum: 1
behaviors[].schedules[].recurrence.day_of_month yes integer Day of the month. In months without this day, the last day of the month is used.; minimum: 1; maximum: 31
behaviors[].schedules[].recurrence_summary yes string Plain-language recurrence, for example Weekly on Monday and Thursday.
behaviors[].schedules[].time_entries yes array
behaviors[].schedules[].time_entries[] yes object
behaviors[].schedules[].time_entries[].id yes string format: uuid
behaviors[].schedules[].time_entries[].kind yes string Values: exact, range
behaviors[].schedules[].time_entries[].preset yes string or null Values: morning, afternoon, evening, night, null
behaviors[].schedules[].time_entries[].start_time yes string Local wall-clock time, 24-hour HH:MM.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
behaviors[].schedules[].time_entries[].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]$
behaviors[].schedules[].time_entries[].label yes string Display label, for example 7:30 AM or Morning.
behaviors[].schedules[].time_summary yes string
behaviors[].schedule_summary yes string
behaviors[].reminders yes object
behaviors[].reminders.browser_enabled yes boolean
behaviors[].reminders.email_enabled yes boolean
behaviors[].reminders.offset_minutes yes integer minimum: 0
behaviors[].reminders.summary yes string
behaviors[].archive_notes yes array
behaviors[].archive_notes[] yes object
behaviors[].archive_notes[].id yes string format: uuid
behaviors[].archive_notes[].archived_at yes string format: date-time; pattern: [Zz]$
behaviors[].archive_notes[].note yes string or null
behaviors[].archive_notes[].updated_at yes string format: date-time; pattern: [Zz]$
behaviors[].external_ref yes string or null This client’s external record id, when it set one at creation.
behaviors[].parent_behavior_id yes string or null Parent Behavior id when this is a sub-behavior. Null for a top-level Behavior (contract 1.7.0).; format: uuid
behaviors[].sub_behavior_sort_order yes integer Position among the parent’s sub-behaviors, 0 first. 0 for a top-level Behavior.; minimum: 0; maximum: 9999
behaviors[].inherit_parent_schedule yes boolean True when this sub-behavior follows its parent’s schedule; its schedules then mirror the parent’s. Always false for a top-level Behavior.
behaviors[].sub_behaviors yes array This Behavior’s sub-behaviors in display order, archived ones included. Empty for a sub-behavior or a Behavior without any.
behaviors[].sub_behaviors[] yes object
behaviors[].sub_behaviors[].id yes string format: uuid
behaviors[].sub_behaviors[].title yes string
behaviors[].sub_behaviors[].sub_behavior_sort_order yes integer Position among the parent’s sub-behaviors, 0 first.; minimum: 0; maximum: 9999
behaviors[].sub_behaviors[].inherit_parent_schedule yes boolean True when the sub-behavior follows its parent’s schedule.
behaviors[].sub_behaviors[].active yes boolean False when the sub-behavior is archived.
behaviors[].sub_behaviors[].run_state yes string Values: running, ended, paused, archived
behaviors[].created_at yes string format: date-time; pattern: [Zz]$
behaviors[].updated_at yes string format: date-time; pattern: [Zz]$
behaviors[].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_-]+$

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": "list_behaviors",
  "arguments": {}
}

Example result

Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.

{
  "behaviors": [
    {
      "id": "00000001-1111-4111-8111-000000000001",
      "title": "Morning walk",
      "description": "Twenty minutes outside.",
      "location_text": null,
      "category": {
        "id": "00000003-1111-4111-8111-000000000003",
        "name": "Fitness"
      },
      "state": "active",
      "archived_at": null,
      "auto_archived_at": null,
      "run_state": "running",
      "is_opportunity": false,
      "end_on": null,
      "end_time": null,
      "pause": null,
      "end_date": null,
      "default_duration_minutes": 20,
      "timezone": "America/New_York",
      "schedules": [
        {
          "id": "00000006-1111-4111-8111-000000000006",
          "recurrence": {
            "frequency": "weekly",
            "interval": 1,
            "days_of_week": [
              "monday",
              "thursday"
            ]
          },
          "recurrence_summary": "Weekly on Monday and Thursday",
          "time_entries": [
            {
              "id": "00000007-1111-4111-8111-000000000007",
              "kind": "exact",
              "preset": null,
              "start_time": "07:30",
              "end_time": null,
              "label": "7:30 AM"
            },
            {
              "id": "00000008-1111-4111-8111-000000000008",
              "kind": "range",
              "preset": "evening",
              "start_time": "18:00",
              "end_time": "00:00",
              "label": "Evening"
            }
          ],
          "time_summary": "7:30 AM, Evening"
        }
      ],
      "schedule_summary": "Weekly on Monday and Thursday at 7:30 AM and Evening",
      "reminders": {
        "browser_enabled": true,
        "email_enabled": false,
        "offset_minutes": 0,
        "summary": "Browser reminder at the scheduled time"
      },
      "archive_notes": [],
      "external_ref": null,
      "parent_behavior_id": null,
      "sub_behavior_sort_order": 0,
      "inherit_parent_schedule": false,
      "sub_behaviors": [],
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-10-18T13:00:00Z",
      "revision": "b1.2026-10-18T13:00:00Z"
    },
    {
      "id": "00000002-1111-4111-8111-000000000002",
      "title": "Vitamin D",
      "description": "Twenty minutes outside.",
      "location_text": null,
      "category": null,
      "state": "archived",
      "archived_at": "2026-10-01T14:00:00Z",
      "auto_archived_at": null,
      "run_state": "archived",
      "is_opportunity": false,
      "end_on": null,
      "end_time": null,
      "pause": null,
      "end_date": null,
      "default_duration_minutes": 20,
      "timezone": "America/New_York",
      "schedules": [
        {
          "id": "00000006-1111-4111-8111-000000000006",
          "recurrence": {
            "frequency": "daily",
            "interval": 1
          },
          "recurrence_summary": "Daily",
          "time_entries": [
            {
              "id": "00000007-1111-4111-8111-000000000007",
              "kind": "exact",
              "preset": null,
              "start_time": "09:00",
              "end_time": null,
              "label": "9:00 AM"
            }
          ],
          "time_summary": "9:00 AM"
        }
      ],
      "schedule_summary": "Weekly on Monday and Thursday at 7:30 AM and Evening",
      "reminders": {
        "browser_enabled": true,
        "email_enabled": false,
        "offset_minutes": 0,
        "summary": "Browser reminder at the scheduled time"
      },
      "archive_notes": [
        {
          "id": "00000009-1111-4111-8111-000000000009",
          "archived_at": "2026-10-01T14:00:00Z",
          "note": "Doctor said to stop.",
          "updated_at": "2026-10-01T14:00:00Z"
        }
      ],
      "external_ref": "facets:rec_42",
      "parent_behavior_id": null,
      "sub_behavior_sort_order": 0,
      "inherit_parent_schedule": false,
      "sub_behaviors": [],
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-10-18T13:00:00Z",
      "revision": "b1.2026-10-18T13:00:00Z"
    }
  ],
  "next_cursor": null
}

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.

Output size limits can also return limit_exceeded. See error handling, limits, and safe retries.