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

# POST /agents/save

`POST /agents/save`

Updates or creates a new agent. If an id is provided, the corresponding agent will be updated. Otherwise, a new agent will be created.

## Headers

- `X-Phantombuster-Org` string

## Request body

- object
  - `id` string — If set, the agent with the corresponding id will be updated.
  - `org` string, nullable — If set, the upserted agent will be linked to the specified organization.
  - `script` string, nullable — If set, the upserted agent will be assigned to the specified script.
  - `branch` string, nullable — If set, the upserted agent will be assigned to the specified branch.
  - `environment` 'staging' | 'release', nullable — If set, the upserted agent will be assigned to the specified environment.
  - `name` string, nullable — Name of the agent.
  - `executionTimeLimit` number, nullable — When set, the execution time of the agent will be limited by the provided value. If this limit is exceeded, the agent will be stopped.
  - `fileMgmt` 'folders' | 'mix' | 'delete', nullable — Agent file management type. The type 'folders' means create new files. The type 'mix' means combine new and previous files. The type 'delete' means delete previous files.
  - `fileMgmtMaxFolders` number, nullable — Max amount of folders for file management.
  - `maxParallelism` number, nullable — Sets the maximum amount of concurrent executions of the agent.
  - `maxRetryNumber` number, nullable — Sets the maximum amount of retries the agent will do before aborting.
  - `launchType` 'manually' | 'repeatedly' | 'once' | 'after agent' — Sets how the agent will be launched. Either "manually", "repeatedly", "once" or "after agent".
  - `launchOnceAt` number, nullable — Must be set when launchType is set to "once". Sets the launch time of the agent.
  - `launchAfterAgentId` string, nullable — Must be set when launchType is set to "after agent". Sets the id of the agent which will trigger the launch of this agent.
  - `repeatedLaunchTimes` object, nullable — Must be set when launchType is set to "repeatedly". Schedules when the agent will be launched automatically.
    - `simplePreset` 'Once every other day' | 'Once per day' | 'Once per day, at the start of the day' | 'Twice per day' | 'Thrice per day' | '4 times per day' | '6 times per day' | '8 times per day' | 'Once every other hour' | 'Once per hour' | 'Twice per hour' | 'Thrice per hour' | '4 times per hour' | 'Once every other working hour' | 'Once per working hour' | 'Twice per working hour' | 'Thrice per working hour' | '4 times per working hour' | 'Once every other working hour, excluding weekends' | 'Once per working hour, excluding weekends' | 'Twice per working hour, excluding weekends' | 'Thrice per working hour, excluding weekends' | '4 times per working hour, excluding weekends', nullable
    - `isSimplePresetEnabled` boolean
    - `timezone` string, required
    - `minute` number[], required
    - `hour` number[], required
    - `day` number[], required
    - `dow` string[], required
    - `month` string[], required
  - `notifications` object, nullable — Sets the notification settings of the agent.
    - `mailAutomaticExitSuccess` boolean
    - `mailAutomaticExitError` boolean
    - `mailAutomaticLaunchError` boolean
    - `mailAutomaticTimeError` boolean
    - `mailManualExitSuccess` boolean
    - `mailManualExitError` boolean
    - `mailManualLaunchError` boolean
    - `mailManualTimeError` boolean
    - `slackWebHook` string
    - `slackAutomaticExitSuccess` boolean
    - `slackAutomaticExitError` boolean
    - `slackAutomaticLaunchError` boolean
    - `slackAutomaticTimeError` boolean
    - `slackManualExitSuccess` boolean
    - `slackManualExitError` boolean
    - `slackManualLaunchError` boolean
    - `slackManualTimeError` boolean
    - `webhook` string — Your custom webhook URL. We will post insightful information about your agent run at this address once it's done. You might be interested in our article on [how to use webhooks](https://hub.phantombuster.com/docs/using-webhooks)
  - `proxyType` 'none' | 'http' | 'pool' | 'squid lease' — If set to "none", no proxy will be used. If set to "http" a single http proxy will be used. If set to "pool" the proxies from the pool will be used.
  - `proxyAddress` string, nullable — When "proxyType" is set to "http", this should be the http address of the proxy. When set to "pool" this should be the name of the proxy pool you wish to use.
  - `proxyUsername` string, nullable — Sets the username used to authenticate the proxy. Should be used when "proxyType" is set to "http".
  - `proxyPassword` string, nullable — Sets the password used to authenticate the proxy. Should be used when "proxyType" is set to "http".
  - `argument` union — Default argument used to launch the agent.
    - string, nullable
    - object, nullable
  - `agentObject` string, nullable — Sets the agent's object. Should be a JSON string.
  - `repeatedLaunchPreset` 'Once every other day' | 'Once per day' | 'Once per day, at the start of the day' | 'Twice per day' | 'Thrice per day' | '4 times per day' | '6 times per day' | '8 times per day' | 'Once every other hour' | 'Once per hour' | 'Twice per hour' | 'Thrice per hour' | '4 times per hour' | 'Once every other working hour' | 'Once per working hour' | 'Twice per working hour' | 'Thrice per working hour' | '4 times per working hour' | 'Once every other working hour, excluding weekends' | 'Once per working hour, excluding weekends' | 'Twice per working hour, excluding weekends' | 'Thrice per working hour, excluding weekends' | '4 times per working hour, excluding weekends', nullable — Automatically sets the agent's launch schedule according to a preset.
  - `applyScriptManifestDefaultSettings` boolean — If true, the manifest's default settings will be applied to the agent.
  - `masterAgentLaunchAfter` number, nullable — Defines when the agent will launch once a slave agent finishes. When not set, the platform chooses a value between 10 and 15 minutes randomly.
  - `masterAgentLaunchOnExitCodes` union — When set, the agent will be launched automatically if the finishing slave agent’s exit code is found in the array or if the value is set to "all".
    - number[], nullable
    - 'all', nullable
  - `squidLeaseIdentifier` object, nullable — Sets the agent's Squid lease configuration.
    - `groupSlug` string, required
    - `refreshRate` integer, required
    - `location` string, nullable
    - `sublocation` string, nullable
  - `persistedVolumeKey` string, nullable — Key identifying the persisted volume to attach to the agent's containers.
  - `wasSetupValidWhenSubmittedByTheFrontend` boolean — If true, the agent's setup is considered complete.
  - `shouldPropagateUpdatedSettingsToWorkersRegardlessOfSessionType` boolean — If true, the updated settings will be propagated to the workers regardless of the session type.
  - `expireAt` number, nullable — The date when the agent will be deleted.
  - `idempotencyKey` string, nullable — Optional key for idempotent operations - only for creating an agent.
  - `internalMetadata` object, nullable — Key-value pairs reserved for PhantomBuster internal use.
  - `userCustomMetadata` object, nullable — User-defined key-value pairs for tagging and filtering agents.

## Response `200`

Agent updated or inserted successfully.

- object
  - `id` string, required

## Other responses

- `400` — No such org, script, branch or environment or invalid parameters provided.
- `401` — Script is not from your org and isn't public or is in staging.
- `402` — Maximum amount of agents reached. Please upgrade your plan to unlock more slots for your agents.
- `412` — Script does not exist in the specified branch.

---

[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)