---
title: "Starts the PerspectivesJob for the given Parameters. If a job is already running, this will raise an error."
method: POST
path: "/perspectives/job/{aspect_id}"
tags: ["perspectives"]
---

# Starts the PerspectivesJob for the given Parameters. If a job is already running, this will raise an error.

`POST /perspectives/job/{aspect_id}`

## Path parameters

- `aspect_id` integer, required

## Request body

- union
  - AddMissingDocsToAspectParams
    - `perspectives_job_type` 'add_missing_docs_to_aspect' — Type of the PerspectivesJob
  - CreateClusterWithNameParams
    - `perspectives_job_type` 'create_cluster_with_name' — 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' — Type of the PerspectivesJob
    - `sdoc_ids` integer[], required — List of source document IDs to include in the cluster.
  - RemoveClusterParams
    - `perspectives_job_type` 'remove_cluster' — Type of the PerspectivesJob
    - `cluster_id` integer, required — ID of the cluster to remove.
  - MergeClustersParams
    - `perspectives_job_type` 'merge_clusters' — 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' — 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' — 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' — Type of the PerspectivesJob
  - ResetModelParams
    - `perspectives_job_type` 'reset_model' — Type of the PerspectivesJob
  - RecomputeClusterTitleAndDescriptionParams
    - `perspectives_job_type` 'recompute_cluster_title_and_description' — Type of the PerspectivesJob
    - `cluster_id` integer, required — ID of the cluster to recompute title and description for.

## Response `200`

Successful Response

- PerspectivesJobRead
  - `job_id` string, required — RQ job ID
  - `job_type` string, 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' — Type of the PerspectivesJob
      - AddMissingDocsToAspectParams
        - `perspectives_job_type` 'add_missing_docs_to_aspect' — Type of the PerspectivesJob
      - CreateClusterWithNameParams
        - `perspectives_job_type` 'create_cluster_with_name' — 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' — Type of the PerspectivesJob
        - `sdoc_ids` integer[], required — List of source document IDs to include in the cluster.
      - RemoveClusterParams
        - `perspectives_job_type` 'remove_cluster' — Type of the PerspectivesJob
        - `cluster_id` integer, required — ID of the cluster to remove.
      - MergeClustersParams
        - `perspectives_job_type` 'merge_clusters' — 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' — 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' — 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' — Type of the PerspectivesJob
      - ResetModelParams
        - `perspectives_job_type` 'reset_model' — Type of the PerspectivesJob
      - RecomputeClusterTitleAndDescriptionParams
        - `perspectives_job_type` 'recompute_cluster_title_and_description' — 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

---

[API](https://skmtc.net/uhh-lt/apis/discourse-analysis-tool-suite-api.md) · [All operations](https://skmtc.net/uhh-lt/apis/discourse-analysis-tool-suite-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uhh-lt/discourse-analysis-tool-suite-api/versions/6b22366ce2d1/schema)