Skip to main content
A Turn represents one round of conversation, typically starting with a user message and finishing with an agent message. Each turn contains multiple items that stream as notifications.

​
Turn Object

​
id
string
Unique turn identifier (e.g., turn_456)
​
items
ThreadItem[]
Array of items in this turn
Only populated on thread/resume or thread/fork responses. For all other responses and notifications, this field is an empty array. Use item/* notifications to track items.
​
status
TurnStatus
Current turn status
  • inProgress - Turn is actively running
  • completed - Turn finished successfully
  • interrupted - Turn was cancelled
  • failed - Turn encountered an error
​
error
TurnError | null
Error details (only populated when status is failed)

​
Start a Turn

Send user input to a thread and begin Codex generation.

​
Method

turn/start

​
Parameters

​
threadId
string
required
Thread ID to add the turn to
​
input
UserInput[]
required
Array of user input items
​
cwd
string
Override working directory for this turn and subsequent turns
​
approvalPolicy
string
Override approval policy
​
sandboxPolicy
SandboxPolicy
Override sandbox policy
​
model
string
Override model for this turn and subsequent turns
​
effort
string
Override reasoning effort (low, medium, high)
​
summary
string
Override reasoning summary mode (concise, verbose)
​
outputSchema
object
JSON Schema to constrain the final assistant message (applies only to this turn)
{
  "type": "object",
  "properties": {
    "answer": { "type": "string" }
  },
  "required": ["answer"],
  "additionalProperties": false
}

​
Response

​
turn
Turn
Initial turn object with status: "inProgress" and empty items array

​
Notifications

The server streams JSON-RPC notifications while the turn is running:
1

turn/started

Initial turn notification
{
  "method": "turn/started",
  "params": {
    "threadId": "thr_123",
    "turn": {
      "id": "turn_456",
      "status": "inProgress",
      "items": [],
      "error": null
    }
  }
}
2

item/* notifications

See Items for full item lifecycle
  • item/started - New item begins
  • item/agentMessage/delta - Streamed text
  • item/completed - Item finishes
3

turn/completed

Final turn notification with status
{
  "method": "turn/completed",
  "params": {
    "threadId": "thr_123",
    "turn": {
      "id": "turn_456",
      "status": "completed",
      "items": [],
      "error": null
    }
  }
}

​
Example: Basic Turn

{
  "method": "turn/start",
  "id": 30,
  "params": {
    "threadId": "thr_123",
    "input": [
      { "type": "text", "text": "Run tests" }
    ]
  }
}

​
Example: Invoke a Skill

Include $<skill-name> in the text input and add a skill input item. 
{
  "method": "turn/start",
  "id": 33,
  "params": {
    "threadId": "thr_123",
    "input": [
      {
        "type": "text",
        "text": "$skill-creator Add a new skill for triaging flaky CI"
      },
      {
        "type": "skill",
        "name": "skill-creator",
        "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
      }
    ]
  }
}

​
Example: Invoke an App

Include $<app-slug> in text and add a mention input with app://<connector-id>. 
{
  "method": "turn/start",
  "id": 34,
  "params": {
    "threadId": "thr_123",
    "input": [
      {
        "type": "text",
        "text": "$demo-app Summarize the latest updates."
      },
      {
        "type": "mention",
        "name": "Demo App",
        "path": "app://demo-app"
      }
    ]
  }
}

​
Interrupt a Turn

Cancel a running turn.

​
Method

turn/interrupt

​
Parameters

​
threadId
string
required
Thread ID
​
turnId
string
required
Turn ID to interrupt

​
Response

​
{}
object
Empty object on success

​
Notifications

After interruption, the server emits turn/completed with status: "interrupted".

​
Example

{
  "method": "turn/interrupt",
  "id": 31,
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456"
  }
}

​
Steer a Turn

Append additional user input to a currently active turn without starting a new turn.

​
Method

turn/steer

​
Parameters

​
threadId
string
required
Thread ID
​
input
UserInput[]
required
Additional user input to append
​
expectedTurnId
string
required
Required active turn ID precondition. Fails if no active turn or ID doesn’t match.

​
Response

​
turnId
string
The active turn ID that accepted the input

​
Example

{
  "method": "turn/steer",
  "id": 32,
  "params": {
    "threadId": "thr_123",
    "input": [
      { "type": "text", "text": "Actually focus on failing tests first." }
    ],
    "expectedTurnId": "turn_456"
  }
}

​
Turn Notifications

​
turn/started
Emitted when a turn beginsPayload: { threadId: string, turn: Turn }
​
turn/completed
Emitted when a turn finishes (completed, interrupted, or failed)Payload: { threadId: string, turn: Turn }
​
turn/diff/updated
Emitted after every fileChange item with turn-level unified diffPayload: { threadId: string, turnId: string, diff: string }
​
turn/plan/updated
Emitted when the agent shares or changes its planPayload:
{
  "threadId": "thr_123",
  "turnId": "turn_456",
  "explanation": "Breaking down the task...",
  "plan": [
    { "step": "Run tests", "status": "completed" },
    { "step": "Fix errors", "status": "inProgress" },
    { "step": "Commit changes", "status": "pending" }
  ]
}
​
model/rerouted
Emitted when the backend reroutes to a different modelPayload: { threadId: string, turnId: string, fromModel: string, toModel: string, reason: string }
​
error
Emitted on mid-turn errorsPayload: { error: TurnError, willRetry: boolean, threadId: string, turnId: string }

​
Next Steps

Items

Understand item types and streaming notifications

Models

List available models and their capabilities