---
title: "Execute complex action (requires x,y)"
method: POST
path: "/api/cmd/ACTION6"
tags: ["Commands"]
---

# Execute complex action (requires x,y)

`POST /api/cmd/ACTION6`

Issues **ACTION 6**—a two-parameter command that supplies explicit
X/Y coordinates—to an active game session.  Common use-cases
include “click/tap at (x,y)”, “place a tile”, or “shoot a
projectile,” depending on the game's mechanics.

Required fields  
• `game_id` — the game to act in  
• `guid`    — session identifier obtained from RESET  
• `x`,`y`   — zero-based grid coordinates (0-63 inclusive)

On success the server applies the action, advances game logic to
the next stable frame, and returns that frame together with the
updated score, state, and win condition.

## Request body

- ComplexActionCommand — Payload for coordinate-based actions (e.g. `/api/cmd/ACTION6`). Supplies an `(x, y)` location on the 64 × 64 game grid along with the game/session identifiers so the engine can apply the action to the correct running instance. **Important:** Include any cookies (especially `AWSALB*` cookies) received from previous RESET or ACTION responses to ensure session affinity.
  - `game_id` string, required — Identifier of the game receiving this action.
  - `guid` string, required — Server-generated session ID obtained from the RESET call.
  - `x` integer, required — Horizontal coordinate on the game grid (0 = left, 63 = right).
  - `y` integer, required — Vertical coordinate on the game grid (0 = top, 63 = bottom).
  - `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` • `guid` not found or does not belong to the supplied `game_id` • `x` or `y` outside the 0-63 range
- `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)