---
updatedAt: 2026-08-18T19:06:55.000Z
agentTools:
  projectIndex: https://developers.nutshell.com/llms.txt
---

# Get tasks and sales process steps

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.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Nutshell API",
    "description": "The most powerful API in the world",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "app.nutshell.com/rest"
    }
  ],
  "paths": {
    "/todos": {
      "get": {
        "tags": [
          "Todos"
        ],
        "summary": "Get tasks and sales process steps",
        "description": "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.",
        "operationId": "4e518d1a14705b0ed69ab378e0364d53",
        "parameters": [
          {
            "name": "filter[assignee]",
            "in": "query",
            "description": "User whose to-dos should be returned. Defaults to the authenticated user. View-restricted users may request only users they can view.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]+-users$",
              "example": "7-users"
            }
          },
          {
            "name": "filter[type]",
            "in": "query",
            "description": "To-do types to include. Multiple values may be comma-separated.",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "tasks",
                  "steps",
                  "follow-ups",
                  "follow-up tasks"
                ]
              }
            }
          },
          {
            "name": "filter[stagesets]",
            "in": "query",
            "description": "Pipeline IDs whose related to-dos should be returned. Multiple values may be comma-separated.",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[0-9]+-stagesets$",
                "example": "1-stagesets"
              }
            }
          },
          {
            "name": "filter[dueTime]",
            "in": "query",
            "description": "Nutshell report-period string, such as a YYYY-MM-DD date or +w2 for the next two weeks, interpreted in the assignee's Nutshell timezone. Ignored when a valid due window is also provided.",
            "schema": {
              "type": "string",
              "example": "2026-08-18"
            }
          },
          {
            "name": "filter[dueWindow]",
            "in": "query",
            "description": "Server-defined due-date bucket, using the assignee's Nutshell timezone.",
            "schema": {
              "type": "string",
              "enum": [
                "overdue",
                "today",
                "tomorrow",
                "upcoming"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Fuzzy search on the task title or sales process step label.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "includeComplete",
            "in": "query",
            "description": "Set to 1 to include completed to-dos with incomplete ones.",
            "schema": {
              "type": "integer",
              "default": 0,
              "enum": [
                0,
                1
              ]
            }
          },
          {
            "name": "onlyComplete",
            "in": "query",
            "description": "Set to 1 to return only completed to-dos, newest first. Takes precedence over includeComplete.",
            "schema": {
              "type": "integer",
              "default": 0,
              "enum": [
                0,
                1
              ]
            }
          },
          {
            "name": "includeDoneFacet",
            "in": "query",
            "description": "Set to 1 to include a done count and keep all facet counts independent of the selected date or completion filter.",
            "schema": {
              "type": "integer",
              "default": 0,
              "enum": [
                0,
                1
              ]
            }
          },
          {
            "name": "onlyDue",
            "in": "query",
            "description": "Set to 0 to include to-dos without a due time.",
            "schema": {
              "type": "integer",
              "default": 1,
              "enum": [
                0,
                1
              ]
            }
          },
          {
            "name": "onlyHotLeads",
            "in": "query",
            "description": "Set to 1 to include only to-dos related to hot leads.",
            "schema": {
              "type": "integer",
              "default": 0,
              "enum": [
                0,
                1
              ]
            }
          },
          {
            "name": "singleStep",
            "in": "query",
            "description": "Set to 0 to allow multiple sales process steps for the same lead when single-step gating is active.",
            "schema": {
              "type": "integer",
              "default": 1,
              "enum": [
                0,
                1
              ]
            }
          },
          {
            "name": "page[startIndex]",
            "in": "query",
            "description": "Zero-based index of the first row. When omitted for an unfiltered incomplete list, the server may center the first page around the overdue/today boundary.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page[limit]",
            "in": "query",
            "description": "Number of rows to return. Defaults to 100.",
            "schema": {
              "type": "integer",
              "default": 100
            }
          },
          {
            "name": "page[endIndex]",
            "in": "query",
            "description": "Inclusive zero-based index of the final row. When present, it determines the page size with page[startIndex].",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of to-dos and facet counts.",
            "content": {
              "application/json": {
                "schema": {
                  "required": [
                    "todos",
                    "meta"
                  ],
                  "properties": {
                    "todos": {
                      "type": "array",
                      "items": {
                        "required": [
                          "id",
                          "type",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "pattern": "^[0-9]+-(tasks|steps)$",
                            "example": "7-tasks"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "tasks",
                              "steps"
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string",
                            "nullable": true
                          },
                          "href": {
                            "description": "REST path for the underlying task or sales process step.",
                            "type": "string"
                          },
                          "dueTime": {
                            "description": "Due time as Unix seconds.",
                            "type": "integer",
                            "format": "int64",
                            "nullable": true
                          },
                          "completedTime": {
                            "description": "Completion time as Unix seconds.",
                            "type": "integer",
                            "format": "int64",
                            "nullable": true
                          },
                          "isCompleted": {
                            "type": "boolean"
                          },
                          "isOverdue": {
                            "type": "boolean"
                          },
                          "isRecurring": {
                            "description": "Present on tasks.",
                            "type": "boolean"
                          },
                          "isSkipped": {
                            "description": "Present on sales process steps.",
                            "type": "boolean"
                          },
                          "delays": {
                            "description": "Postponement choices currently available for a sales process step.",
                            "type": "array",
                            "items": {
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "example": "1-delays"
                                },
                                "name": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "displayLength": {
                                  "type": "string",
                                  "nullable": true
                                }
                              },
                              "type": "object"
                            }
                          },
                          "links": {
                            "description": "API IDs for linked records such as assignee and relatedEntity.",
                            "type": "object"
                          }
                        },
                        "type": "object"
                      }
                    },
                    "relatedEntities": {
                      "description": "Records referenced by todo links, when any are sideloaded.",
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "users": {
                      "description": "Assignees referenced by todo links, when any are sideloaded.",
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "required": [
                        "count",
                        "facets",
                        "page"
                      ],
                      "properties": {
                        "count": {
                          "description": "Total number of matching to-dos across all pages.",
                          "type": "integer",
                          "nullable": true
                        },
                        "facets": {
                          "required": [
                            "past",
                            "today",
                            "tomorrow",
                            "future"
                          ],
                          "properties": {
                            "past": {
                              "type": "integer",
                              "nullable": true
                            },
                            "today": {
                              "type": "integer",
                              "nullable": true
                            },
                            "tomorrow": {
                              "type": "integer",
                              "nullable": true
                            },
                            "future": {
                              "type": "integer",
                              "nullable": true
                            },
                            "done": {
                              "description": "Present only when includeDoneFacet is 1.",
                              "type": "integer",
                              "nullable": true
                            }
                          },
                          "type": "object"
                        },
                        "page": {
                          "required": [
                            "startIndex",
                            "endIndex"
                          ],
                          "properties": {
                            "startIndex": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "endIndex": {
                              "type": "integer",
                              "minimum": 0
                            }
                          },
                          "type": "object"
                        }
                      },
                      "type": "object"
                    },
                    "links": {
                      "description": "Top-level relationship metadata.",
                      "type": "object"
                    }
                  },
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required."
          },
          "403": {
            "description": "The credentials lack read scope, or the authenticated user cannot view the requested assignee's to-dos."
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "tags": [
    {
      "name": "Todos",
      "description": "Todos"
    }
  ]
}
```