---
title: "Get avatar usage"
method: GET
path: "/v1/avatar_usage"
tags: ["Avatars"]
---

# Get avatar usage

`GET /v1/avatar_usage`

Get aggregate usage statistics for avatar conversations, including total duration, session counts, average duration, and a per-day breakdown. Per-day buckets are keyed by UTC calendar date. The date range must not exceed 90 days.

## Query parameters

- `startDate` string, date-time, required
- `endDate` string, date-time, required

## Headers

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

## Response `200`

Success

- object
  - `totalSeconds` integer, required — Total seconds across conversations with a measured duration in the date range.
  - `totalSessions` integer, required — Number of conversations started in the date range. Includes unfinished and failed conversations.
  - `avgDurationSeconds` integer, required — Average duration in seconds across conversations with a measured duration, or 0 if none completed. May not equal `totalSeconds / totalSessions` because unfinished conversations contribute to the session count but not the duration.
  - `byDay` object[], required — Per-day usage across the date range. Days with no sessions are included with zeroes.
    - `date` string, date, required — The UTC calendar date (YYYY-MM-DD).
    - `sessions` integer, required — Number of conversations started on this date.
    - `seconds` integer, required — Total seconds of measured conversation duration on this date.

---

[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/revisions/e7d9a59ac7b0/schema)