---
title: "Turn autopilot on or off for an agent"
method: PUT
path: "/v1/agents/{id}/autonomy"
tags: ["Content Research Agents"]
---

# Turn autopilot on or off for an agent

`PUT /v1/agents/{id}/autonomy`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/agents/{id}/autonomy`
- Auth: HTTP bearer

Turn autopilot on or off. Same switch as `autopilot` on `PUT /v1/agents/:id`. Autopilot is on by default and needs no unlock; it never removes a keyword or exclude term you set. `autonomy_level` ("autopilot" / "suggest") is the older spelling and is still accepted. `cognition_enabled=false` pauses self-optimization entirely. Free.

## Path parameters

- `id` string, required

## Request body

- V1SetAutonomyDto
  - `autopilot` boolean: true turns autopilot on (the default for every agent); false keeps the configuration exactly as you set it.
  - `autonomy_level` 'suggest' | 'autopilot': Older spelling of `autopilot`: "autopilot" = on, "suggest" = off. Send one of the two, not both.
  - `cognition_enabled` boolean: Master switch for self-optimization. false pauses all reflection and changes; true resumes.

## Response `200`

Autonomy updated

- SetAutonomyResponseDto
  - `data` AgentConfigDto, required
    - `id` string, uuid, required
    - `name` string, nullable
    - `is_recurring` boolean, required: false = one-shot (formerly Orbit); true = recurring + cadence (formerly Comet)
    - `active` boolean, required
    - `team_id` string, nullable
    - `source` string, nullable
    - `keywords` string[], required
    - `platforms` string[], required
    - `exclude_keywords` string[], required
    - `exclude_keywords_strict` boolean, required
    - `meta_ads_enabled` boolean, required
    - `data_intelligence_enabled` boolean, required
    - `english_only` boolean, required
    - `intent` string, nullable
    - `intent_keywords` string[], nullable: The expanded keyword set the agent actually searched, derived from your `intent` + `keywords`. Null until the first run resolves it. Useful for seeing how the agent interpreted your intent.
    - `autopilot` boolean, required: Whether autopilot is on. On by default: after each run a recurring agent rewords its searches, adds keywords and follows breaking stories so it keeps finding new videos. It never removes a keyword or exclude term you set. Turn it off with `autopilot: false` on `PUT /v1/agents/:id`.
    - `pinned_keywords` string[], nullable: The keywords you set. Autopilot always keeps these and only adds around them, so `keywords` holds these plus any autopilot added. Replaced whenever you send `keywords`. Null for agents created in the Virlo app.
    - `autonomy_level` 'suggest' | 'autopilot', required: Older two-field spelling of `autopilot`: "autopilot" = on, "suggest" = off. Read `autopilot` instead.
    - `autopilot_unlocked` boolean, required: Legacy field from when autopilot had to be unlocked first; it no longer gates anything. Read `autopilot` instead.
    - `cognition_enabled` boolean, required
    - `cadence` string, nullable: Cron cadence. Null for one-shot agents.
    - `next_run_at` string, nullable
    - `last_run_at` string, nullable
    - `is_processing` boolean, required
    - `created_at` string, required
    - `updated_at` string, required
    - `latest_run` AgentRunDto
      - `id` string, uuid, required
      - `agent_id` string, uuid, required
      - `status` 'pending' | 'processing' | 'completed' | 'partial_failure' | 'failed', required: `pending` and `processing` are in flight. `completed`, `partial_failure` and `failed` are final. `partial_failure` means one platform or keyword failed and the rest of the data is usable.
      - `total_videos_inserted` number, required
      - `total_videos_updated` number, required
      - `total_videos_failed` number, required
      - `videos_linked` number, required
      - `meta_ads_linked` number, required
      - `slideshows_linked` number, required
      - `youtube_count` number, required
      - `tiktok_count` number, required
      - `instagram_count` number, required
      - `exclude_keywords_filtered` number, required
      - `intent_filtered` number, required
      - `language_filtered_count` number, required
      - `duplicates_dropped` number, required
      - `outliers_identified` number, required
      - `trends_detected` string[], nullable
      - `keyword_breakdown` object[], nullable: Per-keyword collection breakdown. One entry per keyword with `keyword`, `videos_inserted`, `videos_updated`, and per-platform counts (`tiktok_count`, `youtube_count`, `instagram_count`). The fastest way to see which keywords are actually producing content.
      - `execution_time_ms` number, required
      - `created_at` string, required
      - `started_at` string, nullable
      - `completed_at` string, nullable
  - `message` string, required

## Other responses

- `400`: No field sent, or `autopilot` and `autonomy_level` disagree
- `401`: Missing or invalid API key (`missing_api_key` / `invalid_api_key`)
- `404`: Agent not found
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)