---
title: "Execute simple action 4"
method: POST
path: "/api/cmd/ACTION4"
tags: ["Commands"]
---

# Execute simple action 4

`POST /api/cmd/ACTION4`

Issues **ACTION 4** to the specified game session.  
This is a single-parameter command (no X/Y coordinates): the exact
in-game effect depends on the title—for example, it might
represent “move right" or “select option D”.

The request must include:
• `game_id` — which game to act on  
• `guid` — the active session identifier returned from RESET  

An optional `reasoning` JSON blob (≤ 16 KB) can be attached for
audit or research purposes.

A successful call returns the next visual frame(s) and updated
score/state.

## Request body

- SimpleActionCommand — Issues a one-parameter action (ACTION1 - ACTION5) to a running game instance identified by `guid`. **Important:** Include any cookies (especially `AWSALB*` cookies) received from previous RESET or ACTION responses to ensure session affinity.
  - `game_id` string, required — Game identifier this action targets.
  - `guid` string, required — Server-generated session ID obtained from a RESET response.
  - `reasoning` object — Optional, caller-defined JSON blob (≤ 16 KB) capturing the agent's internal reasoning, model parameters, or any other metadata you'd like to store alongside the action.

## Response `200`

Frame returned after executing the action.

- FrameResponse — Snapshot returned after every RESET or ACTION command. Includes the latest visual frame(s), cumulative score details, the current game state, and an echo of the triggering action.
  - `game_id` string, required — Game identifier for the running session.
  - `guid` string, required — Server-generated session ID; use this for all subsequent commands.
  - `frame` array[], required — One or more consecutive visual frames. Each frame is a 64 × 64 grid of 4-bit colour indices (integers 0-15). Multiple frames may be returned if the environment advances internally (e.g., animations) before settling.
    - array[]
      - integer[]
  - `state` 'NOT_FINISHED' | 'NOT_STARTED' | 'WIN' | 'GAME_OVER', required — Current state of the session: • **NOT_FINISHED** - game in progress, not yet WIN or GAME_OVER. • **NOT_STARTED** - session has ended (WIN or GAME_OVER) and requires RESET. • **WIN** - session ended in victory. • **GAME_OVER** - session ended in defeat.
  - `levels_completed` integer, required — Current cumulative number of levels completed for this run.
  - `win_levels` integer, required — Level threshold required to reach the **WIN** state. Mirrors the game's configured win condition so agents can adapt dynamically without hard-coding values.
  - `action_input` object, required — Echo of the command that produced this frame.
    - `id` integer — Client-assigned or sequential action index.
    - `data` object — Additional parameters originally sent with the action.
  - `available_actions` integer[], required — List of available actions for the current game.

## Other responses

- `400` — Bad request - possible causes: • Unknown `game_id` or invalid format • `guid` not found or does not belong to `game_id` • `reasoning` field exceeds 16 KB or is malformed
- `401` — Missing or invalid **X-API-Key** header.

---

[API](https://skmtc.net/arcprize/apis/arc-agi-3-rest-api.md) · [All operations](https://skmtc.net/arcprize/apis/arc-agi-3-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arcprize/arc-agi-3-rest-api/versions/195a67c94d38/schema)