---
title: "Record controlled action execution attempt"
method: POST
path: "/controlled-action/execute"
---

# Record controlled action execution attempt

`POST /controlled-action/execute`

## Request

- Base URL: `https://api.gravityads.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gravityads.dev/controlled-action/execute`
- Auth: HTTP bearer

Records the execution attempt. In hosted SaaS, live execution must be queued for the action worker; the request thread does not write ad platforms.

## Request body

- object
  - `action_id` string, required
  - `request_id` string, required
  - `requested_by` string
  - `confirmation` string
  - `platform` string
  - `ad_account_id` string
  - `adapter` 'auto' | 'google_ads_api' | 'meta_official_mcp' | 'microsoft_ads_rest_api' | 'noop': Optional adapter hint. When omitted or auto, the server derives the adapter from the persisted controlled-action platform.
  - `execute_mode` 'dry_run' | 'live': Hosted live execution must hand off to the action worker; request-time adapter dispatch is not allowed in hosted SaaS.
  - `adapter_context` object
  - `execution_note` string
  - `audit_context` object

## Response `200`

Execution result or worker queue handoff

- object
  - `status` string, required
  - `action_id` string
  - `request_id` string
  - `result` object
  - `official_adapter_invocation_plan` object
  - `hosted_action_queue` object
    - `schema_version` 'gravityads.hosted_action_queue_handoff.v1', required
    - `status` string
    - `enabled` boolean, required
    - `queued` boolean, required
    - `tenant_id` string, required
    - `action_id` string, required
    - `request_id` string, required
    - `adapter` string, required
    - `execute_mode` 'dry_run' | 'live', required
    - `database_url_configured` boolean, required
    - `queue_item_id` string
    - `queue_name` string
    - `worker_endpoint` string
    - `idempotency_key` string
    - `action_packet_hash` string
    - `queue_summary` object
    - `raw_secrets_returned` false
  - `adapter_execution` object
    - `skipped` boolean
    - `reason` string
    - `queued` boolean
    - `queue_item_id` string
    - `worker_endpoint` string
    - `platform_write_called` false
  - `platform_write_boundary` object
    - `phase_contract` 'phase2_controlled_actions_worker_only'
    - `execute_mode` string
    - `request_thread_platform_write_called` false
    - `platform_write_called` false
    - `hosted_queue_required` boolean
    - `hosted_queue_queued` boolean
    - `worker_required` boolean
    - `worker_endpoint` string
    - `queue_item_id` string
  - `freshness_gate` object

## Other responses

- `503`: Hosted live execution requires a durable worker queue handoff and failed closed before adapter dispatch.

---

[API](https://skmtc.dev/gravityads/apis/gravityads-api.md) · [All operations](https://skmtc.dev/gravityads/apis/gravityads-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gravityads/apis/gravityads-api/revisions/124cd07d534d?raw)