---
title: "Record controlled action observation"
method: POST
path: "/controlled-action/observe"
---

# Record controlled action observation

`POST /controlled-action/observe`

## 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/observe`
- Auth: HTTP bearer

Records post-action observation and optional metric snapshot in the local action ledger.

## Request body

- object
  - `action_id` string, required
  - `request_id` string, required
  - `observed_by` string
  - `confirmation` string
  - `observation_note` string
  - `metric_snapshot` object
  - `outcome_window` object: Post-action measurement window, for example start_at_utc/end_at_utc/window_label/lookback_days.
  - `baseline_metric_snapshot` object: Metric snapshot before or at the start of the outcome window.
  - `current_metric_snapshot` object: Metric snapshot after the outcome window observation.
  - `attribution` object: Redacted attribution metadata: source/model/confidence/platform_attribution_window_days/assumptions.
  - `evaluation` object: Human or offline evaluation metadata for feedback loops.
  - `audit_context` object

## Response `200`

Observation result

- object
  - `schema_version` string
  - `status` string, required
  - `action_id` string
  - `request_id` string
  - `controlled_action` object
  - `authority_flags` object
    - `platform_write_allowed` boolean
  - `result` object
    - `observation` object
      - `metric_snapshot` object
      - `observation_contract` object
        - `schema_version` 'gravityads.controlled_action_observation_contract.v1', required
        - `contract_schema_version` 'gravityads.controlled_action_observation_contract.v1', required
        - `phase_contract` 'phase2_observe_feedback_outcome_window', required
        - `contract_payload_present` boolean, required
        - `action_id_hash` string
        - `request_id_hash` string
        - `outcome_window` object
        - `metric_snapshot_present` boolean
        - `baseline_metric_snapshot_present` boolean
        - `current_metric_snapshot_present` boolean
        - `metric_delta` object
        - `attribution` object
        - `evaluation` object
        - `raw_platform_ids_returned` false, required
        - `raw_attribution_payload_returned` false, required
        - `raw_customer_ids_returned` false, required
  - `observation_contract` object
    - `schema_version` 'gravityads.controlled_action_observation_contract.v1', required
    - `contract_schema_version` 'gravityads.controlled_action_observation_contract.v1', required
    - `phase_contract` 'phase2_observe_feedback_outcome_window', required
    - `contract_payload_present` boolean, required
    - `action_id_hash` string
    - `request_id_hash` string
    - `outcome_window` object
    - `metric_snapshot_present` boolean
    - `baseline_metric_snapshot_present` boolean
    - `current_metric_snapshot_present` boolean
    - `metric_delta` object
    - `attribution` object
    - `evaluation` object
    - `raw_platform_ids_returned` false, required
    - `raw_attribution_payload_returned` false, required
    - `raw_customer_ids_returned` false, required

---

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