---
title: "Update a pentest launch"
method: PATCH
path: "/v1/pentests/{pentest_slug}/launches/{launch_id}"
tags: ["pentests"]
---

# Update a pentest launch

`PATCH /v1/pentests/{pentest_slug}/launches/{launch_id}`

## Request

- Base URL: `https://api.ethiack.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ethiack.com/v1/pentests/{pentest_slug}/launches/{launch_id}`
- Auth: none declared

Update a launch's mutable fields.

Restricted to machine callers operating within the pentest's scope.

Args:
    pentest_id (int): The parent pentest, resolved and access-checked
        by the router's gate.
    launch_id (int): Identifier of the launch within the pentest.
    body (UpdateLaunchRequest): Fields to update on the launch.
    db (AsyncSession): Request-scoped database session.
    context (ActiveContext): Resolved caller identity and scope.

Returns:
    LaunchResponse: The updated launch.

## Path parameters

- `launch_id` integer, required
- `pentest_slug` string, required

## Request body

- UpdateLaunchRequest: Request body for updating a launch. All fields are optional — only provided fields are applied. Attributes: status (LaunchStatus | None): New execution status. error_info (str | None): Error message to record. start_time (datetime.datetime | None): Execution start. finish_time (datetime.datetime | None): Execution end.
  - `status` 'pending' | 'in_progress' | 'finished' | 'error' | 'canceled': Human-readable launch execution status. Maps to ``StatusEnum`` integer values stored in the database.
  - `error_info` string, nullable: Error message to record.
  - `start_time` string, date-time, nullable: Execution start time.
  - `finish_time` string, date-time, nullable: Execution end time.

## Response `200`

Successful Response

- LaunchResponse: Single launch record in a response. Attributes: id (int): Launch primary key. pentest_id (int): Parent pentest id. machine_user_id (UUID): Machine user that owns the launch. mode (int | None): Artiacker mode code (see :class:`~phoenix.db.models.artiacker.ArtiackerModeType`). status (LaunchStatus): Execution status. error_info (str | None): Truncated error message when the launch ended in :attr:`LaunchStatus.ERROR`. sub_job_id (int | None): Linked ``scan_sub_jobs`` row. start_time (datetime.datetime | None): Execution start. finish_time (datetime.datetime | None): Execution end. created (datetime.datetime): Creation timestamp.
  - `id` integer, required: Launch ID.
  - `pentest_id` integer, required: Parent pentest ID.
  - `machine_user_id` string, uuid, required: Owning machine user ID.
  - `mode` integer, nullable: Artiacker mode code.
  - `status` 'pending' | 'in_progress' | 'finished' | 'error' | 'canceled', required: Human-readable launch execution status. Maps to ``StatusEnum`` integer values stored in the database.
  - `error_info` string, nullable: Error message when the launch failed.
  - `sub_job_id` integer, nullable: Linked scan_sub_jobs row.
  - `start_time` string, date-time, nullable: Execution start time.
  - `finish_time` string, date-time, nullable: Execution end time.
  - `created` string, date-time, required: Creation timestamp.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/ethiack/apis/ethiack-api.md) - [All operations](https://skmtc.dev/ethiack/apis/ethiack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ethiack/apis/ethiack-api/revisions/4eaba89bfebf?raw)