---
title: "Returns the PerspectivesJob for the given ID if it exists"
method: GET
path: "/perspectives/job/{perspectives_job_id}"
tags: ["perspectives"]
---

# Returns the PerspectivesJob for the given ID if it exists

`GET /perspectives/job/{perspectives_job_id}`

## Request

- The document declares no server URL.
- Auth: OAuth 2
  - Password
  - Token URL: `/authentication/login`

## Path parameters

- `perspectives_job_id` string, required

## Response `200`

Successful Response

- PerspectivesJobRead
  - `job_id` string, required: RQ job ID
  - `job_type` 'perspectives', required: Type of the job
  - `project_id` integer, required: Project ID associated with the job
  - `status` 'queued' | 'finished' | 'failed' | 'started' | 'deferred' | 'scheduled' | 'stopped' | 'canceled', required
  - `status_message` string, nullable: Status message
  - `current_step` integer, required: Current step in the job process
  - `steps` string[], required: Total number of steps in the job process
  - `input` PerspectivesJobInput, required
    - `project_id` integer, required: Project ID associated with the job
    - `aspect_id` integer, required: ID of the aspect associated with the PerspectivesJob. -1 if not applicable.
    - `perspectives_job_type` 'create_aspect' | 'add_missing_docs_to_aspect' | 'create_cluster_with_name' | 'create_cluster_with_sdocs' | 'remove_cluster' | 'merge_clusters' | 'split_cluster' | 'change_cluster' | 'refine_model' | 'reset_model' | 'recompute_cluster_title_and_description', required
    - `parameters` union, required: Parameters for the PerspectivesJob. The type depends on the PerspectivesJobType.
      - CreateAspectParams
        - `perspectives_job_type` 'create_aspect', required: Type of the PerspectivesJob
      - AddMissingDocsToAspectParams
        - `perspectives_job_type` 'add_missing_docs_to_aspect', required: Type of the PerspectivesJob
      - CreateClusterWithNameParams
        - `perspectives_job_type` 'create_cluster_with_name', required: Type of the PerspectivesJob
        - `create_dto` ClusterCreate, required
          - `parent_cluster_id` integer, nullable: ID of the parent cluster, if any
          - `aspect_id` integer, required: ID of the aspect this cluster belongs to
          - `level` integer, required: Hierarchical level of the cluster
          - `name` string, required: Name of the cluster
          - `description` string, required: Description of the cluster
      - CreateClusterWithSdocsParams
        - `perspectives_job_type` 'create_cluster_with_sdocs', required: Type of the PerspectivesJob
        - `sdoc_ids` integer[], required: List of source document IDs to include in the cluster.
      - RemoveClusterParams
        - `perspectives_job_type` 'remove_cluster', required: Type of the PerspectivesJob
        - `cluster_id` integer, required: ID of the cluster to remove.
      - MergeClustersParams
        - `perspectives_job_type` 'merge_clusters', required: Type of the PerspectivesJob
        - `cluster_to_keep` integer, required: ID of the cluster to keep after merging.
        - `cluster_to_merge` integer, required: ID of the cluster to delete after merging.
      - SplitClusterParams
        - `perspectives_job_type` 'split_cluster', required: Type of the PerspectivesJob
        - `cluster_id` integer, required: ID of the cluster to split.
        - `split_into` integer, nullable, required: Number of clusters to split the cluster into. Must be greater than 1. If not set, the cluster will be split automatically.
      - ChangeClusterParams
        - `perspectives_job_type` 'change_cluster', required: Type of the PerspectivesJob
        - `sdoc_ids` integer[], required: List of source document IDs to change the cluster for.
        - `cluster_id` integer, required: ID of the cluster to change to. (-1 will be treated as 'removing' the documents / marking them as outliers)
      - RefineModelParams
        - `perspectives_job_type` 'refine_model', required: Type of the PerspectivesJob
      - ResetModelParams
        - `perspectives_job_type` 'reset_model', required: Type of the PerspectivesJob
      - RecomputeClusterTitleAndDescriptionParams
        - `perspectives_job_type` 'recompute_cluster_title_and_description', required: Type of the PerspectivesJob
        - `cluster_id` integer, required: ID of the cluster to recompute title and description for.
  - `output` unknown
  - `created` string, date-time, required: Created timestamp of the job
  - `finished` string, date-time, nullable: Finished timestamp of the job

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-21** `753207b3f495`: 22 info
  - the response property `input/parameters/oneOf[subschema #10: ResetModelParams]/perspectives_job_type` became required for the status `200`
  - the response property `input/parameters/oneOf[subschema #11: RecomputeClusterTitleAndDescriptionParams]/perspectives_job_type` became required for the status `200`
  - the response property `input/parameters/oneOf[subschema #1: CreateAspectParams]/perspectives_job_type` became required for the status `200`
  - the response property `input/parameters/oneOf[subschema #2: AddMissingDocsToAspectParams]/perspectives_job_type` became required for the status `200`
  - …18 more
- **2026-10-05** `3bdfd02830b1`: 1 warning, 1 info
  - added the new `perspectives` enum value to the `job_type` response property for the response status `200`
  - the `job_type` response property const value `perspectives` was added for the status `200`
- **2026-07-16** `bd1187f3520e`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/uhh-lt/apis/discourse-analysis-tool-suite-api/changes/perspectives/job/:perspectives_job_id/get.md)

---

[API](https://skmtc.dev/uhh-lt/apis/discourse-analysis-tool-suite-api.md) - [All operations](https://skmtc.dev/uhh-lt/apis/discourse-analysis-tool-suite-api/llms.txt) - [OpenAPI document](https://skmtc.dev/uhh-lt/apis/discourse-analysis-tool-suite-api/revisions/e498207e29f4?raw)