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

# List Succession Plans

`GET /api/v2/careerhub/succession_plans`

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

## Query parameters

- `start` integer
- `limit` integer
- `incumbentIds` 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, nullable — 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

---

[API](https://skmtc.net/eightfold/apis/api-server-v2-service-service.md) · [All operations](https://skmtc.net/eightfold/apis/api-server-v2-service-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/eightfold/api-server-v2-service-service/versions/0fb26f4e41bf/schema)