---
title: "POST /agents/launch-sync"
method: POST
path: "/agents/launch-sync"
tags: ["agents"]
---

# POST /agents/launch-sync

`POST /agents/launch-sync`

Launches an agent and streams execution status in real-time using NDJSON format. The stream begins with a start message exposing the containerId (so clients can reconnect via /containers/attach on disconnect) and then includes heartbeat messages, execution summary, and error messages if any occur. Optionally includes log lines when the includeLogs body parameter is set to true.

## Headers

- `X-Phantombuster-Org` string

## Request body

- object
  - `id` string, required — Id of the agent to launch.
  - `argument` union — Agent argument. Can either be a JSON string or a plain object. The argument can be retrieved with buster.argument in the agent's script.
    - string
    - object
  - `arguments` union — Agent argument. Can either be a JSON string or a plain object. The argument can be retrieved with buster.argument in the agent's script.
    - string
    - object
  - `bonusArgument` union — Agent bonus argument. Can either be a JSON string or a plain object. This bonus argument is single-use, it will only be used for the current launch. If present, it will be merged with the original argument, resulting in an effective argument that can be retrieved with buster.argument in the agent's script.
    - string
    - object
  - `saveArgument` boolean — If true, argument will be saved as the default launch options for the agent.
  - `saveArguments` boolean — If true, argument will be saved as the default launch options for the agent.
  - `manualLaunch` boolean — If set, the agent will be considered as "launched manually".
  - `maxInstanceCount` number — If set, the agent will only be launched if the number of already running instances is below the specified number.
  - `includeLogs` boolean — If true, agent logs will be included in the stream. Defaults to false.
  - `persistedVolumeKey` string, nullable — Key identifying the persisted volume to attach to the launched container.

## Response `200`

Agent launched successfully. Response is a stream of NDJSON messages with types - start (sent first, with containerId and agentId), heartbeat (periodic keep-alive), logs (container output), summary (final execution result with containerId, executionTime, and optional exitCode), or error (if something goes wrong).

## Other responses

- `400` — A provided parameter is duplicated or the launch argument is too big, or agent not found.

---

[API](https://skmtc.dev/phantombuster/apis/phantombuster-api-v2.md) · [All operations](https://skmtc.dev/phantombuster/apis/phantombuster-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/phantombuster/phantombuster-api-v2/revisions/acf0049d7c7f/schema)