GET agent/chats/chatId — Google Flow API

Read an agent chat

October 16, 2026

Request Headers
Query Parameters
Responses
Chat status
Agent items
Media
Model
Examples
Try It

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

chatId is required, URL-encoded in the path (it contains : and @), from POST /agent/chats or GET /agent/chats.

Request Headers

Authorization: Bearer {API token}

API token is required, see Setup useapi.net for details.

Query Parameters

media is optional. Set false to skip the media status and link refresh.
Default: true.

Responses

200 OK

A chat where the agent asked before making a video, the request was approved, and the video finished (ui and some items left out):

{
  "chatId": "c-u12345-email:[email protected]:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow",
  "email": "[email protected]",
  "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": "thinking", "text": "**Validating Initial Specs**\n\nI'm starting by ensuring \"Veo 3.1 - Lite\" is a valid model…" },
        { "kind": "tool_call", "tool": "ask_for_permission", "args": { "total_cost": 10, "num_total": 1, "num_images": 0, "num_videos": 1 } }
      ],
      "media": []
    },
    {
      "turn": 2,
      "message": { "text": "Approve", "references": [] },
      "agent": [
        {
          "kind": "text",
          "text": "",
          "choices": [{ "label": "Option 1", "value": "option_1", "description": "A paper boat floating on a calm pond." }]
        },
        {
          "kind": "tool_result",
          "tool": "generate_video_from_text",
          "result": {
            "status": "queued",
            "media_id": "97aa051d-419f-40fd-a200-f5593d997822",
            "workflow_id": "dce57a4a-481e-4b3f-a84f-0a7f20e0b41c",
            "display_name": "Paper boat floating on pond",
            "model_key": "veo_3_1_t2v_lite",
            "aspect_ratio": "VIDEO_ASPECT_RATIO_LANDSCAPE"
          }
        },
        { "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_from_text",
          "workflowId": "dce57a4a-481e-4b3f-a84f-0a7f20e0b41c",
          "model": "veo_3_1_t2v_lite",
          "displayName": "Paper boat floating on pond",
          "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:

{
  "status": "waiting_approval",
  "pendingApproval": { "turn": 1, "cost": 10, "images": 0, "videos": 1, "total": 1 },
  "lastError": null
}

400 Bad Request

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
}

401 Unauthorized

Invalid API token.

{
  "error": "useapi.net ⁝ Unauthorized",
  "code": 401
}

403 Forbidden

The chatId belongs to another useapi.net user.

{
  "error": "This chat belongs to another user",
  "code": 403
}

404 Not Found

The chat was deleted, or its account is not added.

{
  "error": "Chat not found: it was deleted or never existed",
  "code": 404
}

503 Service Unavailable

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/email and 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_from_text` 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:

referenceId is the id to reuse: pass it as referenceImage_N or referenceVideo_1 to POST /images, POST /videos or your next agent message.
status is queued while a video is being made, completed when it is ready, and failed when Google could not make it, with error and failureReasons. An item the agent’s tool refused right away has status error with Google’s code in error.
url is the link to the file, on completed items 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

{ // TypeScript, all fields are optional
  chatId: string
  email: string
  projectId: string
  title?: string                 // Google titles each chat, usually soon after its first turn
  created: string
  updated: string
  status: 'running' | 'waiting_approval' | 'failed' | 'idle'
  pendingApproval: {
    turn: number
    cost?: number                // Flow credits
    images?: number
    videos?: number
    total?: number
  } | null
  lastError: {
    turn: number
    code: string                 // see Turn errors
    message: string
    httpStatus?: number
    at: string
  } | null
  turns: {
    turn: number
    message: {                   // your message
      text: string               // @-mentions read as @Image I, @Character I or the voice name
      references: { type: 'media' | 'voice' | 'character', id: string }[]
    }
    agent: (
      | { kind: 'text', text: string, choices?: { label: string, value?: string, mediaId?: string, description?: string }[], ui?: unknown }
      | { kind: 'thinking', text: string }
      | { kind: 'tool_call', tool: string, args: Record<string, unknown> }
      | { kind: 'tool_result', tool: string, result: Record<string, unknown> }
      | { kind: 'error', code: unknown }
    )[]
    media: {
      referenceId: string
      mediaId: string
      type: 'image' | 'video'
      status: 'queued' | 'completed' | 'failed' | 'error' | string
      tool: string               // the tool that made it, e.g. generate_image
      workflowId?: string
      model?: string             // e.g. veo_3_1_t2v_lite
      displayName?: string
      url?: string               // completed only, expires after about 6 hours
      durationSec?: number       // videos
      error?: string
      failureReasons?: string[]
    }[]
  }[]
}

Examples

CHATID="c-u12345-email:[email protected]: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.