---
title: "Report an agent activity-state signal for a session"
method: POST
path: "/api/v1/sessions/{sessionId}/activity"
tags: ["sessions"]
---

# Report an agent activity-state signal for a session

`POST /api/v1/sessions/{sessionId}/activity`

## Path parameters

- `sessionId` string, required — Session identifier, e.g. project-1.

## Request body

- SetActivityRequest
  - `agentSessionId` string — Native agent session identifier used to resume its transcript.
  - `conversationCheckpointOrigin` 'human' | 'coordination' — Whether the main-turn boundary came from a human or AO coordination.
  - `coordinationId` string — Opaque identity of an AO-authored semantic prompt accepted by the native agent.
  - `event` string — AO hook sub-command that produced this state (e.g. post-tool-use).
  - `latestAssistantUpdate` string — Latest assistant update exposed by the provider hook.
  - `latestUserPrompt` string — Latest real user prompt exposed by the provider hook.
  - `launchId` string — AO process generation that produced the signal.
  - `observedAt` string, date-time — Time the local hook process observed the event, before delivery to the daemon.
  - `providerTurnId` string — Native main-turn identity reported by the hook, when supported.
  - `state` 'active' | 'idle' | 'waiting_input' | 'blocked' | 'exited' — Agent activity state reported by an agent hook. Optional for metadata-only hooks.
  - `submissionId` string — AO prompt-hook context correlation UUID, when supported.
  - `toolName` string — Native tool name, for tool-use hook events.
  - `toolUseId` string — Native tool-use id, for tool-use hook events.
  - `transcriptPath` string — Read-only provider-native transcript path exposed by the hook.
  - `usage` UsageHookMetadata
    - `harness` 'claude-code' | 'codex', required
    - `modelId` string
    - `providerId` string — Canonical provider routing hint derived by the trusted local Claude hook.
    - `subagentId` string
    - `subagentTranscriptPath` string
    - `transcriptPath` string

## Response `200`

OK

- SetActivityResponse
  - `ok` boolean, required
  - `sessionId` string, required
  - `state` string, required

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `500` — Internal Server Error
- `501` — Not Implemented

## Changes

- **2026-09-23** `c9673ebc394b` — 1 info
  - added the new optional request property `coordinationId`
- **2026-09-16** `7e89f751104a` — 1 info
  - added the new optional request property `observedAt`
- **2026-09-14** `fe5d127437ea` — 3 info
  - added the new optional request property `conversationCheckpointOrigin`
  - added the new optional request property `providerTurnId`
  - added the new optional request property `submissionId`
- **2026-09-03** `d31a2d019c47` — 4 info
  - added the optional property `reporting_owner` to the response with the `400` status
  - added the optional property `reporting_owner` to the response with the `404` status
  - added the optional property `reporting_owner` to the response with the `500` status
  - added the optional property `reporting_owner` to the response with the `501` status
- **2026-08-28** `e853ada076ff` — 1 info
  - added the new optional request property `usage/providerId`

[Full history](https://skmtc.dev/composiohq/apis/agent-orchestrator-http-daemon/changes/api/v1/sessions/:sessionId/activity/post.md)

---

[API](https://skmtc.dev/composiohq/apis/agent-orchestrator-http-daemon.md) · [All operations](https://skmtc.dev/composiohq/apis/agent-orchestrator-http-daemon/llms.txt) · [OpenAPI document](https://skmtc.dev/composiohq/apis/agent-orchestrator-http-daemon/revisions/cfaec3fcda51?raw)