---
title: "Get conversation"
method: GET
path: "/v1/avatar_conversations/{id}"
tags: ["Avatars"]
---

# Get conversation

`GET /v1/avatar_conversations/{id}`

Get detailed information about a specific conversation, including the transcript and recording download URL when available. The conversation ID is the same value returned when the realtime session was created.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-Runway-Version` '2024-11-06', required

## Response `200`

Success

- union
  - object — A conversation that is currently active.
    - `id` string, uuid, required — Unique conversation identifier. This is the same value as the realtime session ID for the call.
    - `name` string, required — Conversation name.
    - `avatar` union, required — The avatar used in this conversation, or null if unavailable.
      - object — A preset avatar.
        - `type` 'runway-preset', required
        - `presetId` string, required — The preset avatar ID.
      - object — A custom avatar created by the user.
        - `type` 'custom', required
        - `id` string, uuid, nullable, required — The custom avatar ID, or null if deleted.
        - `name` string, nullable, required — The avatar name, or null if unavailable.
        - `imageUrl` string, uri, nullable, required — URL to the avatar image, or null if unavailable.
    - `createdAt` string, date-time, required — When the conversation was created.
    - `maxDuration` integer, nullable, required — Maximum allowed duration in seconds, or null if not set.
    - `transcript` object[], required — The conversation transcript.
      - `role` 'user' | 'assistant', required — Who produced this transcript entry.
      - `content` string, nullable, required — The spoken text, or null for tool-only turns.
      - `timestamp` string, date-time, nullable, required — When this entry occurred, or null if unavailable.
      - `toolCalls` object[] — Tool invocations made during this assistant turn. Only present on assistant entries.
        - `id` string — Optional identifier linking this call to its result.
        - `name` string, required — The name of the tool that was called.
        - `arguments` object, required — The arguments passed to the tool.
      - `toolResults` object[] — Tool results received during this assistant turn. Only present on assistant entries.
        - `id` string — Optional identifier linking this result to its call.
        - `name` string, required — The name of the tool that returned a result.
        - `result` union — The tool result (object, string, or null).
          - object
          - string
        - `error` string, nullable — Error message if the tool call failed.
        - `durationMs` number, nullable — How long the tool call took in milliseconds.
    - `recordingUrl` string, uri, nullable, required — A URL to download the conversation recording, or null if no recording is available. This URL will expire within 24-48 hours, fetch the conversation again to get a fresh download URL.
    - `tools` object[], required — The tools that were configured for this conversation session. Empty if no tools were used.
      - `type` 'client_event' | 'backend_rpc', required — The tool type.
      - `name` string, required — The tool name.
      - `description` string, required — A description of when and how the tool should be used.
    - `status` 'in_progress', required
    - `startedAt` string, date-time, nullable, required — When the conversation started, or null if not yet started.
    - `duration` integer, nullable, required — Elapsed duration in seconds, or null if not yet started.
  - object — A conversation that completed successfully.
    - `id` string, uuid, required — Unique conversation identifier. This is the same value as the realtime session ID for the call.
    - `name` string, required — Conversation name.
    - `avatar` union, required — The avatar used in this conversation, or null if unavailable.
      - object — A preset avatar.
        - `type` 'runway-preset', required
        - `presetId` string, required — The preset avatar ID.
      - object — A custom avatar created by the user.
        - `type` 'custom', required
        - `id` string, uuid, nullable, required — The custom avatar ID, or null if deleted.
        - `name` string, nullable, required — The avatar name, or null if unavailable.
        - `imageUrl` string, uri, nullable, required — URL to the avatar image, or null if unavailable.
    - `createdAt` string, date-time, required — When the conversation was created.
    - `maxDuration` integer, nullable, required — Maximum allowed duration in seconds, or null if not set.
    - `transcript` object[], required — The conversation transcript.
      - `role` 'user' | 'assistant', required — Who produced this transcript entry.
      - `content` string, nullable, required — The spoken text, or null for tool-only turns.
      - `timestamp` string, date-time, nullable, required — When this entry occurred, or null if unavailable.
      - `toolCalls` object[] — Tool invocations made during this assistant turn. Only present on assistant entries.
        - `id` string — Optional identifier linking this call to its result.
        - `name` string, required — The name of the tool that was called.
        - `arguments` object, required — The arguments passed to the tool.
      - `toolResults` object[] — Tool results received during this assistant turn. Only present on assistant entries.
        - `id` string — Optional identifier linking this result to its call.
        - `name` string, required — The name of the tool that returned a result.
        - `result` union — The tool result (object, string, or null).
          - object
          - string
        - `error` string, nullable — Error message if the tool call failed.
        - `durationMs` number, nullable — How long the tool call took in milliseconds.
    - `recordingUrl` string, uri, nullable, required — A URL to download the conversation recording, or null if no recording is available. This URL will expire within 24-48 hours, fetch the conversation again to get a fresh download URL.
    - `tools` object[], required — The tools that were configured for this conversation session. Empty if no tools were used.
      - `type` 'client_event' | 'backend_rpc', required — The tool type.
      - `name` string, required — The tool name.
      - `description` string, required — A description of when and how the tool should be used.
    - `status` 'ended', required
    - `startedAt` string, date-time, nullable, required — When the conversation started.
    - `endedAt` string, date-time, nullable, required — When the conversation ended.
    - `duration` integer, nullable, required — Duration of the conversation in seconds.
  - object — A conversation that ended due to an error.
    - `id` string, uuid, required — Unique conversation identifier. This is the same value as the realtime session ID for the call.
    - `name` string, required — Conversation name.
    - `avatar` union, required — The avatar used in this conversation, or null if unavailable.
      - object — A preset avatar.
        - `type` 'runway-preset', required
        - `presetId` string, required — The preset avatar ID.
      - object — A custom avatar created by the user.
        - `type` 'custom', required
        - `id` string, uuid, nullable, required — The custom avatar ID, or null if deleted.
        - `name` string, nullable, required — The avatar name, or null if unavailable.
        - `imageUrl` string, uri, nullable, required — URL to the avatar image, or null if unavailable.
    - `createdAt` string, date-time, required — When the conversation was created.
    - `maxDuration` integer, nullable, required — Maximum allowed duration in seconds, or null if not set.
    - `transcript` object[], required — The conversation transcript.
      - `role` 'user' | 'assistant', required — Who produced this transcript entry.
      - `content` string, nullable, required — The spoken text, or null for tool-only turns.
      - `timestamp` string, date-time, nullable, required — When this entry occurred, or null if unavailable.
      - `toolCalls` object[] — Tool invocations made during this assistant turn. Only present on assistant entries.
        - `id` string — Optional identifier linking this call to its result.
        - `name` string, required — The name of the tool that was called.
        - `arguments` object, required — The arguments passed to the tool.
      - `toolResults` object[] — Tool results received during this assistant turn. Only present on assistant entries.
        - `id` string — Optional identifier linking this result to its call.
        - `name` string, required — The name of the tool that returned a result.
        - `result` union — The tool result (object, string, or null).
          - object
          - string
        - `error` string, nullable — Error message if the tool call failed.
        - `durationMs` number, nullable — How long the tool call took in milliseconds.
    - `recordingUrl` string, uri, nullable, required — A URL to download the conversation recording, or null if no recording is available. This URL will expire within 24-48 hours, fetch the conversation again to get a fresh download URL.
    - `tools` object[], required — The tools that were configured for this conversation session. Empty if no tools were used.
      - `type` 'client_event' | 'backend_rpc', required — The tool type.
      - `name` string, required — The tool name.
      - `description` string, required — A description of when and how the tool should be used.
    - `status` 'failed', required
    - `startedAt` string, date-time, nullable, required — When the conversation started, or null if it failed before starting.
    - `endedAt` string, date-time, nullable, required — When the conversation ended, or null if it failed before starting.
    - `duration` integer, nullable, required — Duration in seconds, or null if the conversation failed before starting.
    - `failure` string, required — A human-friendly reason for the failure. We do not recommend returning this to users directly without adding context.
    - `failureCode` string, required — A machine-readable error code for the failure. See https://docs.dev.runwayml.com/errors/task-failures/ for more information.

---

[API](https://skmtc.net/runwayml/apis/runwayml-api.md) · [All operations](https://skmtc.net/runwayml/apis/runwayml-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/runwayml/runwayml-api/versions/e7d9a59ac7b0/schema)