GetItDoneGetItDone Docs
API ReferenceTask occurrences

List a task's occurrences

Cursor-paginated ledger of the days a repeating task is due, most recent day first. Filter with `status`, and with `starting_on` / `ending_on` for a calendar window (both inclusive, and both interpreted in the recurrence's own timezone). Future days already exist inside the materialization horizon — that is what makes completing early possible. A task that does not repeat answers an empty page rather than 404. Every filter is baked into the cursor: reusing an `after` cursor with different filters answers 400 `validation_failed`.

GET
/v1/tasks/{task_id}/occurrences

Cursor-paginated ledger of the days a repeating task is due, most recent day first. Filter with status, and with starting_on / ending_on for a calendar window (both inclusive, and both interpreted in the recurrence's own timezone). Future days already exist inside the materialization horizon — that is what makes completing early possible. A task that does not repeat answers an empty page rather than 404. Every filter is baked into the cursor: reusing an after cursor with different filters answers 400 validation_failed.

Authorization

bearerAuth
AuthorizationBearer <token>

A gid_ API key (Settings → API keys) or an OAuth 2.1 access token.

In: header

Path Parameters

task_id*string

Task short id, e.g. T-123 (a bare 123 is also accepted on input).

Match^(?:T-)?[0-9]{1,12}$

Query Parameters

limit?integer

Maximum number of items to return (1-100).

Range1 <= value <= 100
Default25
after?string

Opaque cursor from a previous page's next_cursor — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different limit) answers 400 validation_failed.

status?string

Only occurrences currently in this state.

Value in

  • "PENDING"
  • "COMPLETED"
  • "SKIPPED"
  • "MISSED"
starting_on?string

Only occurrences on or after this calendar day (YYYY-MM-DD).

Match^\d{4}-\d{2}-\d{2}$
ending_on?string

Only occurrences on or before this calendar day (YYYY-MM-DD).

Match^\d{4}-\d{2}-\d{2}$

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/v1/tasks/string/occurrences"
{  "data": [    {      "task_id": "string",      "occurrence_date": "string",      "sequence": -9007199254740991,      "status": "PENDING",      "completed_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

Remove a blocker DELETE

Removes the blocked-by link between the two tasks — neither task is otherwise touched, and completion history is untouched. Removing a link that is not there succeeds unchanged, so retries are safe. When this frees the task (its last OPEN blocker is gone), the `task.unblocked` webhook fires — the same event a blocker being completed or archived produces. Answers the task's full dependency view after the removal.

Complete or skip one day PATCH

Marks ONE day of a repeating task completed or skipped — the SAME shared operation the MCP `complete_task_occurrence` tool executes. The day may be in the PAST ("I brushed my teeth yesterday") or a scheduled FUTURE day finished early; neither breaks the chain, and neither touches any other day or the task's own `status`. Re-sending the state a day is already in is a no-op success, so retries are safe. A day the schedule does not produce (or a task that does not repeat) answers 404 `resource_not_found`.