---
title: "List Succession Plans"
method: GET
path: "/api/v2/careerhub/succession_plans"
tags: ["Succession Plan"]
---

# List Succession Plans

`GET /api/v2/careerhub/succession_plans`

## Request

- Base URL: `https://apiv2.eightfold.ai`
- URL: `https://apiv2.eightfold.ai/api/v2/careerhub/succession_plans`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/eightfold/apis/api-server-v2-service-service/docs/api/v2/careerhub/succession_plans/get.ts> (a function with typed inputs; its response is checked against the schema)

Search and get a list of succession plans based on the search parameters given

## Query parameters

- `start` integer
- `limit` integer
- `incumbentIds` string
- `successorIds` string
- `query` string
- `exclude` string
- `keyList` string

## Headers

- `Authorization` string, required

## Response `200`

OK

- object
  - `data` SuccessionPlanSchema[]
    - `createdAt` integer, nullable: Timestamp representing creation date and time of the succession plan
    - `associatedRoleId` string, nullable: Eightfold role ID associated with the succession plan
    - `jobCode` string, nullable: External job code of the incumbent(s)
    - `caretakers` SuccessionPlanCaretaker[], nullable: Caretaker profile IDs of the succession plan
      - `createdAt` integer, nullable: Timestamp when the caretaker was first added to the plan
      - `employeeId` string, nullable: ATS/HRIS employee ID of the caretaker
      - `updatedAt` integer, nullable: Timestamp when the caretaker data was last updated
      - `profileId` integer, nullable: Eightfold decoded profile ID (numeric) of the caretaker
    - `entityId` string, nullable: ATS/HRIS position ID associated with the plan
    - `positionCriticalityTags` string[], nullable: Criticality tags of the succession plan that is associated with the position held by the incumbent
    - `incumbents` SuccessionPlanIncumbent[], nullable: Incumbents of the succession plan
      - `externalJobId` string, nullable: Position ID associated with the incumbent in ATS/HRIS
      - `employeeId` string, nullable: ATS/HRIS employee ID of the incumbent
      - `profileId` integer, nullable: Eightfold decoded profile ID (numeric) of the incumbent
    - `planType` string, nullable: Type of the succession plan Ex. either "position" or "role" (only honored for POST)
    - `planName` string, nullable: Name of the succession plan
    - `successors` SuccessionPlanSuccessor[], nullable: Successors of the succession plan
      - `createdAt` integer, nullable: Timestamp when the successor was first added to the plan
      - `order` integer, nullable: Order of the successor within its succession state group
      - `profileId` integer, nullable: Eightfold decoded profile ID (numeric)
      - `employeeId` string, nullable: ATS/HRIS employee ID of the successor
      - `matchScores` EmployeeMatchScoreSchema[], nullable: Match score details
        - `matchType` string, nullable: Match score criteria
        - `rawScore` number, float, nullable: Raw match score in float
        - `topMatches` string[], nullable: Top items matched based on the match type
        - `score` integer, nullable: Rounded match score in integer
      - `updatedAt` integer, nullable: Timestamp when the successor data was last updated
      - `state` string, required: Succession state of the successor
    - `updatedAt` integer, nullable: Timestamp representing the updation date and time of the succession plan
    - `metricFields` SuccessionPlanMetricFields
      - `insightTag` string[], nullable: Tags to highlight key aspects of the plan
      - `pipelineStrength` string, nullable: Strength of the plan’s successor pipeline
      - `femalePercentage` number, float, nullable: Percentage of female successors in the plan
      - `diverseEthnicityPercentage` number, float, nullable: Percentage of diverse-ethnicity successor in the plan
    - `roleCriticalityTags` string[], nullable: Criticality tags of the role that is associated with the position held by the incumbent
    - `positionId` integer, required: Eightfold position ID associated with the succession plan
    - `description` string, nullable: Description of the succession plan
  - `meta` MetaSchema
    - `totalCount` integer, nullable
    - `pageTotalCount` integer, nullable
    - `pageStartIndex` integer, nullable

## Changes

- **2026-11-03** `9a8b3a927e93`: 2 info
  - added the new optional `query` request parameter `successorIds`
  - the response property `data/items/successors/items/state` became required for the status `200`

[Operation history](https://skmtc.dev/eightfold/apis/api-server-v2-service-service/changes/api/v2/careerhub/succession_plans/get.md)

---

[API](https://skmtc.dev/eightfold/apis/api-server-v2-service-service.md) - [All operations](https://skmtc.dev/eightfold/apis/api-server-v2-service-service/llms.txt) - [OpenAPI document](https://skmtc.dev/eightfold/apis/api-server-v2-service-service/revisions/9a8b3a927e93?raw)