---
title: "Skip the occurrence a reminder is on (reminder_only model)."
method: POST
path: "/tasks/{id}/recurrence/skip"
tags: ["tasks"]
---

# Skip the occurrence a reminder is on (reminder_only model).

`POST /tasks/{id}/recurrence/skip`

## Request

- Base URL: `https://restivity.ai/api/v1`
- URL: `https://restivity.ai/api/v1/tasks/{id}/recurrence/skip`
- Auth: OAuth 2 (authorization code, authorization URL `https://restivity.ai/oauth/authorize`, token URL `https://restivity.ai/api/oauth/token`, scopes: `tasks:write`)

For a recurring master whose `recurrence_model` is `reminder_only` (TIPO B): the master is always ON one occurrence — its `due_date`. This moves it to the next occurrence not before today WITHOUT recording a completion (no rewards); overdue occurrences in between are skipped and counted in `skipped_count`. When the rule has no further occurrence the master is completed and `series_completed` is true. To record the occurrence as DONE, PATCH the task with `status: "completed"` instead — that rolls it the same way, with the completion rewards. A non-recurring task, a `materialized` master or a child occurrence is refused with 400 `invalid_request`. As on the web, whoever may edit the task skips it — an editor of its project on a teammate's reminder included; a team viewer is 403 `forbidden`. MCP sibling: `tasks_recurrence_skip`.

## Path parameters

- `id` string, uuid, required

## Response `201`

Where the reminder was and where it is now, plus the updated task.

- SkipReminderOccurrenceResponse
  - `success` boolean, required
  - `previous_date` string, nullable, required: The occurrence it was on (YYYY-MM-DD).
  - `next_date` string, nullable, required: The occurrence it is on now (YYYY-MM-DD); null when the series ended.
  - `skipped_count` integer, required: Overdue occurrences between the two, skipped (never completed one by one).
  - `series_completed` boolean, required: No further occurrence: the master was completed for real.
  - `task` Task, required
    - `id` string, uuid, required
    - `user_id` string, uuid, required
    - `project_id` string, uuid, nullable, required
    - `title` string, required
    - `description` string, required: The stored HTML, as the task editor writes it (sanitized). To show it to a person read `description_text`.
    - `description_text` string, required: The description as plain text: every tag removed, one line per block, `- ` / `N. ` before list items, entities decoded — the same shape as a comment’s `content_text`. Show THIS to a person; `description` is the stored HTML. Read-only
    - `status` 'todo' | 'in_progress' | 'completed' | 'archived', required: Lifecycle state of a task.
    - `priority` 'low' | 'medium' | 'high' | 'urgent', required
    - `order` integer, nullable, required
    - `due_date` string, nullable, required
    - `is_for_today` boolean, required
    - `is_important` boolean, required
    - `is_urgent` boolean, required
    - `estimated_pomodoros` integer, required
    - `completed_pomodoros` integer, required
    - `is_recurring` boolean, required
    - `recurring_frequency` string, nullable, required
    - `recurring_end_date` string, nullable, required
    - `recurring_days` integer[], nullable, required
    - `parent_recurrence_id` string, uuid, nullable, required
    - `recurrence_model` 'materialized' | 'reminder_only', nullable, required
    - `recurrence_start_date` string, nullable, required: RES-115 — the series anchor ("Starts on") of a recurring master, a civil date at UTC midnight. The deadline is only a deadline: a `reminder_only` master's `due_date` is the occurrence it is currently on (it rolls forward when the occurrence is completed or skipped), a `materialized` master has none (each child occurrence carries its own). NULL on non-recurring rows and on child occurrences.
    - `completed_at` string, nullable, required
    - `assigned_to` string, uuid, nullable, required
    - `code` string, nullable, required
    - `created_at` string, required
    - `updated_at` string, required
    - `deleted_at` string, nullable, required
    - `url` string
    - `subtasks` Subtask[]
      - `id` string, uuid, required
      - `task_id` string, uuid, required
      - `title` string, required
      - `completed` boolean, required
      - `order` integer, nullable
      - `created_at` string
    - `tags` TagRef[]
      - `id` string, uuid, required
      - `user_id` string, uuid, required
      - `name` string, required
      - `color` string, required
      - `usage_count` integer, required
      - `deleted_at` string, nullable
    - `project` ProjectRef
      - `id` string, uuid, required
      - `name` string, required
      - `color` string, required
      - `prefix` string, nullable
      - `team_id` string, uuid, nullable
      - `team_name` string, nullable
      - `team_slug` string, nullable
    - `project_status` ProjectStatusRef
      - `id` string, uuid, required
      - `name` string, required
      - `color` string, required
      - `category` 'todo' | 'in_progress' | 'completed', required: Lifecycle category of a custom project status.
    - `assigned_to_profile` AssignedProfileRef
      - `id` string, uuid, required
      - `display_name` string, required
      - `photo_url` string, nullable, required
    - `planned_occurrences` PlannedOccurrence[]: AGF-381 — only on the master of a `materialized` series, from `tasks_get`: the next occurrences that do not exist yet (the nightly job creates each one 30 days before its day), up to the series end and at most 12, after the occurrences that already exist (those are real child tasks: `parent_recurrence_id` = this id). Absent on every other task and on list endpoints.
      - `date` string, required: The day of the occurrence (YYYY-MM-DD).
      - `creates_on` string, required: The day the nightly job creates it as a real task (YYYY-MM-DD): the date minus 30 days.
    - `series_change` SeriesChange
      - `change` 'to_reminder' | 'stop_repeating', required: `to_reminder`: the series is now a `reminder_only` master; `stop_repeating`: it is now a plain task.
      - `trashed_occurrence_ids` string[], required: The occurrences still to come (due today or later, not completed) — now in the Trash, restorable.
      - `kept_occurrence_ids` string[], required: The past and the completed occurrences — live, still linked to the series (`parent_recurrence_id`).
      - `reminder_due_date` string, nullable, required: `to_reminder`: the day the reminder is due (YYYY-MM-DD) — its next occurrence from today; null otherwise.

## Other responses

- `400`: Invalid request shape.
- `401`: Missing or invalid access token.
- `403`: Token lacks the required scope — or `forbidden`: the caller can read this task but may not edit it (a team viewer; only an editor of its project can). Nothing written.
- `404`: No such task visible to the caller.
- `409`: Transient, nothing written — send the same request again: `status_palette_busy` (the status list changed while the write waited) or `deadlock` (another change of the status list met this write).
- `422`: Request body failed schema validation.
- `429`: Rate-limit exceeded for this tier.

---

[API](https://skmtc.dev/restivity/apis/restivity-rest-api.md) · [All operations](https://skmtc.dev/restivity/apis/restivity-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/restivity/apis/restivity-rest-api/revisions/5764e41ebb3a?raw)