Lives list
GET /api/v1/lives returns the publicly visible livestreams on the platform — scheduled, on air, interrupted, and ended streams (with their replays).
Contract at a glance
Section titled “Contract at a glance”| Item | Value |
|---|---|
| Method and path | GET /api/v1/lives |
| Full URL | https://ohmy.xin/api/v1/lives |
| Authentication | Bearer key required |
| Request body | None |
| Response | data is an array of live objects, meta.pagination carries the page info |
| Pagination | Cursor based, 20 items per page by default, 100 maximum |
| Visibility | Only directory-listed streams in public circles are returned |
Request
Section titled “Request”GET /api/v1/lives HTTP/1.1Host: ohmy.xinAuthorization: Bearer omx_live_xxxxxxxx_yyyyyyyy...Accept: application/jsonAuthentication, rate limiting, and the error envelope follow the shared API conventions; this page covers only what is specific to the endpoint.
Query parameters
Section titled “Query parameters”Every parameter is optional. Calling the endpoint with no parameters returns the first page in the default sort order.
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 20 |
Items per page, between 1 and 100. Out-of-range values return 400. |
cursor |
string | — | The meta.pagination.next_cursor from the previous page. An opaque string — send it back verbatim. |
sort |
string | created_at:desc |
Sort order: created_at:desc (newest first by creation time) or updated_at:desc (newest first by update time). |
circle_number |
string | — | Filter by circle, using the circle’s number (up to 32 characters). |
state |
string | scheduled,live,interrupted |
Filter by state, comma-separated. Allowed values: scheduled, live, interrupted, ended. |
scheduled_after |
ISO 8601 timestamp | — | Lower bound on scheduled_at (inclusive). |
scheduled_before |
ISO 8601 timestamp | — | Upper bound on scheduled_at (inclusive). |
updated_after |
ISO 8601 timestamp | — | Lower bound on updated_at (inclusive). |
Example request
Section titled “Example request”curl -s "https://ohmy.xin/api/v1/lives?limit=2&state=scheduled,live&circle_number=7000101526" \ -H "Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy..."Response
Section titled “Response”data[] fields
Section titled “data[] fields”data is an array; each element describes one livestream.
| Field | Type | Nullable | Description |
|---|---|---|---|
number |
string | No | The stream’s public number. The internal id is never returned. |
title |
string | No | Stream title. |
description |
string | Yes | Stream description; null when there is none. |
kind |
string | No | Stream kind — always video today. |
state |
string | No | State: scheduled, live, interrupted, or ended. |
url |
string | No | The room URL — share it directly with users. |
cover_url |
string | Yes | Cover image URL; null when there is none. |
viewer_count |
integer | Yes | Current viewers. Only populated while the stream is on air (live / interrupted); null in every other state. |
scheduled_at |
ISO 8601 timestamp | Yes | Scheduled start time. |
started_at |
ISO 8601 timestamp | Yes | Actual start time. |
ended_at |
ISO 8601 timestamp | Yes | End time. |
duration_seconds |
integer | No | Stream duration in seconds; 0 before it starts or before it ends. |
replay_available |
boolean | No | Whether a replay is available: true once the stream has ended, the replay is visible, and a recording is ready. |
comments_count |
integer | No | Number of comments. |
reminders_count |
integer | No | Number of reminders. |
updated_at |
ISO 8601 timestamp | No | Last update time. |
circle |
object | No | The circle that owns the stream. |
host |
object | Yes | The host; null when unavailable. |
circle fields
Section titled “circle fields”| Field | Type | Nullable | Description |
|---|---|---|---|
number |
string | No | Circle number — feed it straight into the circle_number filter. |
name |
string | No | Circle name. |
url |
string | No | Circle home page, in the live channel view. |
avatar_url |
string | Yes | Circle avatar URL. |
host fields
Section titled “host fields”| Field | Type | Nullable | Description |
|---|---|---|---|
name |
string | No | Host display name. |
avatar_url |
string | Yes | Host avatar URL. |
meta.pagination fields
Section titled “meta.pagination fields”| Field | Type | Nullable | Description |
|---|---|---|---|
limit |
integer | No | The page size actually applied. |
has_more |
boolean | No | Whether another page exists. |
next_cursor |
string | Yes | Cursor for the next page; null when has_more is false. |
Example response
Section titled “Example response”{ "data": [ { "number": "9100004", "title": "On air now", "description": "Weekly market outlook", "kind": "video", "state": "live", "url": "https://ohmy.xin/circles/7000101526/lives/9100004", "cover_url": "https://ohmy.xin/circles/7000101526/lives/9100004/card_cover.png?v=1a2b3c4d", "viewer_count": 42, "scheduled_at": null, "started_at": "2024-01-16T10:00:00+08:00", "ended_at": null, "duration_seconds": 0, "replay_available": false, "comments_count": 12, "reminders_count": 7, "updated_at": "2024-01-16T10:30:00+08:00", "circle": { "number": "7000101526", "name": "Crypto Lab", "url": "https://ohmy.xin/circles/7000101526?channel=live", "avatar_url": "https://cdn.ohmy.xin/circles/7000101526/avatar.webp" }, "host": { "name": "Alice", "avatar_url": "https://cdn.ohmy.xin/users/a1b2c3/avatar.webp" } } ], "meta": { "pagination": { "limit": 20, "has_more": false, "next_cursor": null }, "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}Pagination
Section titled “Pagination”Pagination is cursor based: fetch the first page, take meta.pagination.next_cursor, pass it back as the cursor parameter on the next call, and stop when has_more is false.
# First pagecurl -s "https://ohmy.xin/api/v1/lives?limit=2" \ -H "Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy..."
# Next page — pass the previous next_cursor back verbatimcurl -s "https://ohmy.xin/api/v1/lives?limit=2&cursor=eyJzIjoidHJlYXRlZF9hdDpkZXNjIiwiYyI6WyIyMDI0LTAxLTE2VDAyOjAwOjAwWiIsOTEwMDAwNF19" \ -H "Authorization: Bearer omx_live_xxxxxxxx_yyyyyyyy..."Visibility rules
Section titled “Visibility rules”A livestream appears in the list only when all of these hold:
- The host has listed it in the circle’s livestream directory (
directory_listedis true); - Its state is
scheduled,live,interrupted, orended; - Its circle is bound to Mixin, not dormant, and set to public.
Errors
Section titled “Errors”Beyond the shared envelope, this endpoint adds one case:
| HTTP status | error.code |
When it happens |
|---|---|---|
400 |
invalid_parameter |
A query parameter is invalid: limit out of range, an illegal sort/state value, a malformed timestamp, an inverted time window, or an invalid cursor. |
The 400 response lists each offending parameter in error.details:
{ "error": { "code": "invalid_parameter", "message": "Invalid query parameter: state must contain only: scheduled, live, interrupted, ended.", "details": [ { "param": "state", "reason": "must contain only: scheduled, live, interrupted, ended" } ] }, "meta": { "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f" }}For the other status codes (401, 429, 503, 500), see the API conventions.
Related pages
Section titled “Related pages”- API reference — authentication, rate limits, response envelope, and error codes
- Quickstart — create an account, generate a key, make your first call
- Strategies list — the other list endpoint
- OpenAPI spec — the machine-readable description of this endpoint (OpenAPI 3.1)