---
title: "Get tasks and sales process steps"
method: GET
path: "/todos"
tags: ["Todos"]
---

# Get tasks and sales process steps

`GET /todos`

Returns the authenticated user's to-dos, or another viewable user's to-dos when filter[assignee] is provided. OAuth access tokens require the read scope. Date windows and facets use the assignee's Nutshell timezone.

## Query parameters

- `filter[assignee]` string
- `filter[type]` string[]
- `filter[stagesets]` string[]
- `filter[dueTime]` string
- `filter[dueWindow]` 'overdue' | 'today' | 'tomorrow' | 'upcoming'
- `q` string
- `includeComplete` 0 | 1
- `onlyComplete` 0 | 1
- `includeDoneFacet` 0 | 1
- `onlyDue` 0 | 1
- `onlyHotLeads` 0 | 1
- `singleStep` 0 | 1
- `page[startIndex]` integer
- `page[limit]` integer
- `page[endIndex]` integer

## Response `200`

A page of to-dos and facet counts.

- object
  - `todos` object[], required
    - `id` string, required
    - `type` 'tasks' | 'steps', required
    - `title` string, required
    - `description` string, nullable
    - `href` string — REST path for the underlying task or sales process step.
    - `dueTime` integer, nullable — Due time as Unix seconds.
    - `completedTime` integer, nullable — Completion time as Unix seconds.
    - `isCompleted` boolean
    - `isOverdue` boolean
    - `isRecurring` boolean — Present on tasks.
    - `isSkipped` boolean — Present on sales process steps.
    - `delays` object[] — Postponement choices currently available for a sales process step.
      - `id` string
      - `name` string, nullable
      - `displayLength` string, nullable
    - `links` object — API IDs for linked records such as assignee and relatedEntity.
  - `relatedEntities` object[] — Records referenced by todo links, when any are sideloaded.
  - `users` object[] — Assignees referenced by todo links, when any are sideloaded.
  - `meta` object, required
    - `count` integer, nullable, required — Total number of matching to-dos across all pages.
    - `facets` object, required
      - `past` integer, nullable, required
      - `today` integer, nullable, required
      - `tomorrow` integer, nullable, required
      - `future` integer, nullable, required
      - `done` integer, nullable — Present only when includeDoneFacet is 1.
    - `page` object, required
      - `startIndex` integer, required
      - `endIndex` integer, required
  - `links` object — Top-level relationship metadata.

## Other responses

- `401` — Authentication required.
- `403` — The credentials lack read scope, or the authenticated user cannot view the requested assignee's to-dos.

---

[API](https://skmtc.dev/nutshell/apis/nutshell-api.md) · [All operations](https://skmtc.dev/nutshell/apis/nutshell-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nutshell/nutshell-api/revisions/14f59cf6a09a/schema)