Read an agent chat

October 16, 2026 (November 16, 2026)

Table of contents

  1. Request Headers
  2. Query Parameters
  3. Responses
  4. Chat status
  5. Agent items
  6. Media
  7. Model
  8. Examples
  9. 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

Request Headers
Authorization: Bearer {API token}
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: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 (ui left 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": []
        }
      ]
    }
    
  • 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 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

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.