---
updatedAt: 2026-04-20T19:14:52.000Z
agentTools:
  projectIndex: https://developers.nutshell.com/llms.txt
---

# Get a list of stages

Returns active stages from active pipelines that are visible to the authenticated user. OAuth access tokens require the read scope. When pipeline visibility is enabled, stages in restricted pipelines are omitted unless the authenticated user is an administrator or the pipeline is shared directly or through a team.

# 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": {
    "/stages": {
      "get": {
        "tags": [
          "Stagesets (Pipelines)"
        ],
        "summary": "Get a list of stages",
        "description": "Returns active stages from active pipelines that are visible to the authenticated user. OAuth access tokens require the read scope. When pipeline visibility is enabled, stages in restricted pipelines are omitted unless the authenticated user is an administrator or the pipeline is shared directly or through a team.",
        "operationId": "14af5dd687ab31f65e5af1a2b1fa5527",
        "responses": {
          "200": {
            "description": "Stages visible to the authenticated user.",
            "content": {
              "application/json": {
                "schema": {
                  "required": [
                    "meta",
                    "links",
                    "stages"
                  ],
                  "properties": {
                    "meta": {
                      "$ref": "#/components/schemas/meta"
                    },
                    "links": {
                      "description": "Top-level relationship metadata for stage pipelines.",
                      "type": "object"
                    },
                    "stages": {
                      "type": "array",
                      "items": {
                        "required": [
                          "id",
                          "type",
                          "name",
                          "description",
                          "position",
                          "activeAvatarUrl",
                          "completeAvatarUrl",
                          "incompleteAvatarUrl",
                          "overdueAvatarUrl",
                          "links"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "pattern": "^[0-9]+-stages$",
                            "example": "1-stages"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "stages"
                            ]
                          },
                          "name": {
                            "type": "string",
                            "example": "Prospecting"
                          },
                          "description": {
                            "type": "string",
                            "example": "Identify and qualify potential customers"
                          },
                          "position": {
                            "type": "integer",
                            "minimum": 0,
                            "example": 1
                          },
                          "activeAvatarUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "completeAvatarUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "incompleteAvatarUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "overdueAvatarUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "links": {
                            "required": [
                              "stageset"
                            ],
                            "properties": {
                              "stageset": {
                                "type": "string",
                                "pattern": "^[0-9]+-stagesets$",
                                "example": "1-stagesets"
                              }
                            },
                            "type": "object"
                          }
                        },
                        "type": "object"
                      }
                    }
                  },
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required."
          },
          "403": {
            "description": "The OAuth access token does not include the read scope."
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "meta": {
        "description": "Information about the Nutshell instance making the request",
        "properties": {
          "instanceId": {
            "description": "The Nutshell instance ID",
            "type": "string",
            "example": "12345"
          },
          "siteId": {
            "description": "Site ID for WebFX customers",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "tags": [
    {
      "name": "Stagesets (Pipelines)",
      "description": "Stagesets (Pipelines)"
    }
  ]
}
```