Read an agent chat
October 16, 2026 (November 16, 2026)
Table of contents
Read a whole chat from Google: each turn with your message, everything the agent did in reply, the images and videos it made with their status and links, and where the chat stands now. Use it to show a chat, to check on a turn after a 504 or a 502, to see whether a video has finished, or to get fresh media links. To follow a chat live, use GET /agent/chats/chatId/stream.
Media links point to Google and expire about 6 hours after they are issued. Each read brings the newest 50 media items up to date and gives finished ones a fresh link. Pass media=false for a faster read that leaves media as the agent reported them, without links.
https://api.useapi.net/v1/google-flow/agent/chats/
chatId?media=media
chatIdis required, URL-encoded in the path (it contains:and@), from POST /agent/chats or GET /agent/chats.
Request Headers
Authorization: Bearer {API token}
API tokenis required, see Setup useapi.net for details.
Query Parameters
mediais optional. Setfalseto skip the media status and link refresh.
Default:true.
Responses
-
A chat where the agent asked before making a video, the request was approved, and the video finished (
uiand some items left out):{ "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow", "email": "john@gmail.com", "projectId": "f166200a-ea22-461a-bc68-47ff6d3ee500", "created": "2026-10-16T22:03:14.000Z", "updated": "2026-10-16T22:03:52.410Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Make one 8 second video with Veo 3.1 - Lite of a paper boat floating on a calm pond.", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate a video of a paper boat floating on a calm pond using Veo 3.1 - Lite with a duration of 8 seconds." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "text": "This will generate 1 video, costing 10 credits. Do you want to proceed?", "total_cost": 10, "num_images": 0, "num_videos": 1 } }, { "kind": "tool_result", "tool": "generate_video", "result": { "media_id": "97aa051d-419f-40fd-a200-f5593d997822", "workflow_id": "dce57a4a-481e-4b3f-a84f-0a7f20e0b41c", "status": "queued", "model_key": "veo_3_1_t2v_lite", "display_name": "Veo 3.1 - Lite", "prompt": "A paper boat floating on a calm pond" } }, { "kind": "text", "text": "Your video of a paper boat on a calm pond has been scheduled. Feel free to check back in a few minutes!" } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:97aa051d-419f-40fd-a200-f5593d997822", "mediaId": "97aa051d-419f-40fd-a200-f5593d997822", "type": "video", "status": "completed", "tool": "generate_video", "workflowId": "dce57a4a-481e-4b3f-a84f-0a7f20e0b41c", "model": "veo_3_1_t2v_lite", "displayName": "Veo 3.1 - Lite", "url": "https://flow-content.google/video/97aa051d-419f-40fd-a200-f5593d997822?Expires=...&KeyName=labs-flow-prod-cdn-key&Signature=...", "durationSec": 8 } ] } ] }A chat waiting for an approval (
uileft out):{ "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:7f172583-43db-4907-92fa-a8cba64e7cd3-bot:google-flow", "email": "john@gmail.com", "projectId": "f166200a-ea22-461a-bc68-47ff6d3ee500", "title": "Green Ball Rolling Motion", "created": "2026-11-11T02:31:33.950Z", "updated": "2026-11-11T02:31:52.412Z", "status": "waiting_approval", "pendingApproval": { "turn": 1, "cost": 4, "images": 0, "videos": 1 }, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Generate one 4 second video of a green ball rolling. Cheapest video model.", "references": [] }, "agent": [ { "kind": "text", "text": "I'll generate one 4-second video of a green ball rolling using Omni 1.1 Flash at 360p resolution." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "text": "This will generate 1 video, costing 4 credits. Do you want to proceed?", "total_cost": 4, "num_images": 0, "num_videos": 1 } } ], "media": [] } ] } -
The path value is not a
chatId.{ "error": "Path parameter chatId (not-a-chat-id) is not a chat id from POST /agent/chats or GET /agent/chats", "code": 400 } -
Invalid API token.
{ "error": "useapi.net ⁝ Unauthorized", "code": 401 } -
The
chatIdbelongs to another useapi.net user.{ "error": "This chat belongs to another user", "code": 403 } -
The chat was deleted, or its account is not added.
{ "error": "Chat not found: it was deleted or never existed", "code": 404 } -
Google Flow could not be reached, and nothing happened. Retry shortly.
{ "error": "Google Flow is not reachable right now and could not read the chat. Retry", "code": 503 } -
596 Session Error
The account’s Google session is no longer valid. Delete the account with DELETE /accounts/
emailand add it again by following Setup Google Flow.
Chat status
status | Meaning |
|---|---|
running | A turn is running. Sending a message answers 409 until it ends. |
waiting_approval | The agent asks before it spends credits, see pendingApproval. Answer with POST /agent/chats/chatId/approval, or send a new message to move on. |
failed | The last turn failed, see lastError. Send the next message when you are ready. |
idle | Nothing is running. Send the next message at any time. |
lastError is kept for about 15 minutes after the turn ends. After that the chat reads idle, and the history shows what the cut-short turn made. Its code is one of the turn errors.
Agent items
Each turn’s agent array lists what the agent did, in order:
kind | Fields | Meaning |
|---|---|---|
text | text, choices, ui | A reply. text is the readable text. choices are options the agent offers, such as a tile for each image or video it made, with a label, value, description and the mediaId of the image or video the option shows. To pick one, send its text as your next message. ui is the agent’s raw reply layout as Google sends it, for apps that want to draw it the way the Flow web app does. |
thinking | text | The agent’s reasoning, as Google shows it. |
tool_call | tool, args | A tool the agent called, for example generate_image, generate_video or ask_for_permission (the approval request). |
tool_result | tool, result | What the tool returned. A generation result carries media_id, status and display_name, and on a refusal status error with Google’s error_code. |
error | code | An error Google reported inside the turn. |
The tool names and their args and result come from Google unchanged, so new ones can appear at any time.
Media
Each turn’s media array lists the images and videos the agent made in that turn:
referenceIdis the id to reuse: pass it asreferenceImage_NorreferenceVideo_1to POST /images, POST /videos or your next agent message.statusisqueuedwhile a video is being made,completedwhen it is ready, andfailedwhen Google could not make it, witherrorandfailureReasons. An item the agent’s tool refused right away has statuserrorwith Google’s code inerror.urlis the link to the file, oncompleteditems only. It expires about 6 hours after it was issued.
Images are ready when the turn ends. Videos usually finish a minute or two later.
Model
The chat with its status, the spend approval it waits for, the last error and every turn.
The chat and its turns, field by field
{ // TypeScript, all fields are optional
chatId: string // the chat's id, it carries the account, the project and Google's chat id
email: string // the account the chat runs on
projectId: string // the Google Flow project the chat is in
title?: string // Google titles each chat, usually soon after its first turn
created: string // ISO 8601 timestamp, from Google
updated: string // ISO 8601 timestamp of the chat's last activity, from Google
status: 'running' | 'waiting_approval' | 'failed' | 'idle' // running: a turn is in progress. waiting_approval: the
// agent waits for your spend approval. failed: the last turn ended with an error, see
// lastError. idle: nothing is in progress
pendingApproval: { // the spend approval the chat waits for, null when there is none
turn: number // the turn that asks
cost?: number // Google Flow credits
images?: number // images it will make
videos?: number // videos it will make
} | null
lastError: { // why the last turn failed, null otherwise; kept for about 15 minutes after the turn ended
turn: number // the turn that failed
code: string // INTERRUPTED (the connection to Google broke), GOOGLE_ERROR (Google ended or refused the
// turn), UNREADABLE_ANSWER (no readable reply), TIMEOUT (past Google's 10-minute limit),
// CAPTCHA_FAILED (Google refused every captcha, nothing ran), AGENT_QUOTA (Google's daily
// agent limit) or NOT_STARTED (the turn was never sent to Google, nothing ran)
message: string // what went wrong
httpStatus?: number // the HTTP status of the failure
at: string // ISO 8601 timestamp, when the turn ended
} | null
turns: { // every turn of the chat, oldest first
turn: number // turn number, from 1
message: { // your message
text: string // @-mentions read as @Image I, @Character I or the voice name
references: { // the media, voices and characters your message used
type: 'media' | 'voice' | 'character', // what it is
id: string // Google's id of that media, voice or character
}[]
}
agent: ( // what the agent did in reply, in order
| {
kind: 'text', // a reply
text: string, // the readable text
choices?: { // options the agent offers, such as a tile for each image or video it made
label: string, // the option's text
value?: string, // the option's value
mediaId?: string, // the image or video the option shows
description?: string // the option's description
}[],
ui?: unknown // the agent's raw reply layout as Google sends it
}
| {
kind: 'thinking', // the agent's reasoning
text: string // as Google shows it
}
| {
kind: 'tool_call', // a tool the agent called
tool: string, // e.g. `generate_image`, `generate_video` or `ask_for_permission` (the approval request)
args: Record<string, unknown> // what the agent passed to the tool
}
| {
kind: 'tool_result', // what a tool returned
tool: string, // the tool's name
result: Record<string, unknown> // a generation result carries `media_id`, status and `display_name`
}
| {
kind: 'error', // an error Google reported in the turn
code: unknown // Google's error code
}
)[]
media: { // the images and videos this turn made
referenceId: string // the id to reuse as a reference in POST /images, POST /videos or your next message
mediaId: string // Google's media id
type: 'image' | 'video' // image or video
status: 'queued' | 'completed' | 'failed' | 'error' | string // queued or running: being made. completed: ready.
// failed: Google could not make it. error: the tool refused it
tool: string // the tool that made it, e.g. `generate_image`
workflowId?: string // Google's workflow id that holds the media
model?: string // Google's own key for the model that ran
displayName?: string // the model name the Google Flow web app shows, e.g. Veo 3.1 - Lite
url?: string // completed only, expires after about 6 hours
durationSec?: number // a finished video's length in seconds, when Google reports it (not on images)
error?: string // Google's error code (error) or error message (failed)
failureReasons?: string[] // Google's failure reasons, failed videos only
}[]
}[]
}
Examples
-
CHATID="c-u12345-email:john@gmail.com-project:f166200a-...-chat:2a0f1973-...-bot:google-flow" curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/agent/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")" -
const token = 'YOUR_API_TOKEN' const chatId = 'chatId from POST /agent/chats' const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/chats/${encodeURIComponent(chatId)}`, { headers: { 'Authorization': `Bearer ${token}` } }) const chat = await response.json() console.log(chat.status) for (const turn of chat.turns) for (const m of turn.media) console.log(turn.turn, m.type, m.status, m.url ?? '') -
import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' chatId = 'chatId from POST /agent/chats' r = requests.get( f'https://api.useapi.net/v1/google-flow/agent/chats/{quote(chatId, safe="")}', headers={'Authorization': f'Bearer {token}'}, ) chat = r.json() print(chat['status']) for turn in chat['turns']: for m in turn['media']: print(turn['turn'], m['type'], m['status'], m.get('url', ''))
Try It
Finished images and videos are shown under the JSON.