---
title: "Start a retest"
method: POST
path: "/retests"
tags: ["Retests", "Beta"]
---

# Start a retest

`POST /retests`

## Request

- Base URL: `https://public.escape.tech/v3`
- URL: `https://public.escape.tech/v3/retests`
- Auth: API key in header `X-ESCAPE-API-KEY`

Start an issue retest on a DAST or AI pentest profile. Provide either issueIds or filter, not both. The returned id is the scan id.

## Request body

- object
  - `profileId` string, uuid, required: The profile ID to retest
  - `issueIds` string[]: Explicit issue IDs to retest. Provide this or filter, not both.
  - `filter` object: Issue filter. Matches issues on the given profile.
    - `ids` string[]: Filter by specific issue IDs
    - `blacklistedIds` string[]: Exclude these issue IDs
    - `blacklistedNames` string[]: Exclude issues by their raw name (e.g. 'SQL injection')
    - `projectIds` string[]: Filter by project IDs
    - `assetIds` string[]: Filter by asset IDs
    - `targetIds` string[]: Filter by target IDs
    - `scanIds` string[]: Filter by scan IDs
    - `tagIds` string[]: Filter by tag IDs
    - `securityTestUids` string[]: Filter by security test UIDs
    - `domains` string[]: Filter by domain
    - `names` string[]: Filter by issue full name (the display name including risk characteristics, e.g. 'SQL injection found on external-facing asset')
    - `search` string: Search term to filter issues by name or description
    - `jiraTicket` boolean: Filter by issues with Jira tickets
    - `noTags` true: Filter by issues whose assets have no tags. Only `true` is supported: the API cannot express "assets that have tags", so `false` is rejected instead of silently matching every issue.
    - `aiFalsePositive` boolean: Filter by AI false positive classification
    - `agentic` boolean: Filter by agentic (AI pentest) issues
    - `risks` string[]: Filter by risk types
    - `assetClasses` string[]: Filter by asset classes
    - `categories` string[]: Filter by issue categories
    - `assetTypes` string[]: Filter by asset types
    - `assetStatuses` string[]: Filter by asset statuses
    - `scannerKinds` string[]: Filter by scanner kinds
    - `severities` string[]: Filter by issue severities
    - `status` string[]: Filter by issue status
    - `dnf` object: Advanced filter as a DNF expression (JSON object)
  - `context` string: Optional operator context for the retest agents
  - `initiator` 'CI' | 'MANUAL' | 'SCHEDULED': The initiator of the retest

## Response `200`

OK

- object
  - `id` string, uuid, required: The scan ID of the retest
  - `profileId` string, required: The profile the retest ran on
  - `status` string, required: The scan status of the retest
  - `progressRatio` number, required: The progress ratio of the retest scan
  - `createdAt` string, required: The date and time the retest was created
  - `finishedAt` string, nullable, required: The date and time the retest finished
  - `context` string, nullable, required: Optional operator context passed when starting the retest
  - `agents` object[], required: Retest agents with status and outcome
    - `id` string, uuid, nullable, required: The agent id. Null until the agent has started.
    - `issueId` string, uuid, required: The issue this agent retests
    - `status` 'FAILED' | 'FINISHED' | 'RUNNING' | 'null', nullable, required: The agent run status. Null until the agent has started.
    - `outcome` 'FAILED' | 'NOT_TESTED' | 'VERIFIED_FIXED' | 'VULNERABLE' | 'null', nullable, required: The retest outcome. Null while the report is still pending.

## Other responses

- `400`: Bad Request

---

[API](https://skmtc.dev/escape/apis/escape-public-api.md) - [All operations](https://skmtc.dev/escape/apis/escape-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/escape/apis/escape-public-api/revisions/2eab35df40c7?raw)