REALITY APIreality.app ↗
Fetch REALITY virtual live streaming event listings, detailed event metadata, and participant leaderboard rankings via 3 structured API endpoints.
What is the REALITY API?
The REALITY App API exposes 3 endpoints covering the full lifecycle of broadcaster events on the REALITY virtual live streaming platform. Use list_events to pull the complete catalog of past and present events in a single response, get_event to retrieve per-event metadata including schedule dates and icon assets, and get_event_results to page through ranked participant standings with streamer profile data.
No input parameters required.
curl -X POST 'https://api.parse.bot/scraper/8d14cfba-9676-4392-9222-ffae438647c0/list_events' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace reality-app-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: REALITY App Events SDK — browse events, fetch details, check leaderboards."""
from parse_apis.REALITY_App_Events_API import Reality, NotFoundError
client = Reality()
# List event summaries — limit= caps TOTAL items fetched.
for event in client.event_summaries.list(limit=3):
print(event.title, event.event_type, event.begin_at)
# Drill-down: get full event detail from a summary.
summary = client.event_summaries.list(limit=1).first()
if summary:
detail = summary.details()
print(detail.title, detail.thresholds, detail.show_score)
# Fetch an event directly by ID and browse its leaderboard.
try:
event = client.events.get(event_id="23542")
print(event.title, event.begin_at, event.end_at)
except NotFoundError as exc:
print(f"Event not found: {exc}")
# Iterate leaderboard participants for that event.
if event:
for participant in event.results(limit=5):
print(participant.rank, participant.nickname, participant.score)
print("exercised: event_summaries.list / summary.details / events.get / event.results")
List all broadcaster events on REALITY platform. Returns the full catalog of past and present events with summary metadata including dates, thresholds, and category. No pagination — returns all events in a single response.
No input parameters required.
{
"type": "object",
"fields": {
"total": "integer",
"events": "array of event summaries"
},
"sample": {
"data": {
"total": 881,
"events": [
{
"title": "【イベント終了】REALITY × あおぎり高校 YouTube Shorts コラボ出演争奪戦！Vol.2",
"end_at": "2025-12-21T15:00:00Z",
"status": 3,
"open_at": "2025-12-05T09:00:00Z",
"begin_at": "2025-12-15T09:00:00Z",
"close_at": "2026-06-21T15:00:00Z",
"event_id": 21752,
"icon_url": "https://image-api.reality.wrightflyer.net/api/v1/image/event-icon/21752/1761880742",
"page_url": "https://reality.app/events/21752",
"event_type": 1,
"thresholds": [
0
],
"category_id": 0,
"internal_title": "REALITY × あおぎり高校 YouTube Shorts コラボ出演争奪戦！Vol.2",
"header_image_url": "https://image-api.reality.wrightflyer.net/api/v1/image/event-header/21752/1761880743",
"number_of_groups": 1,
"number_of_winners": 1
}
]
},
"status": "success"
}
}About the REALITY API
Event Catalog and Detail
list_events takes no inputs and returns the full catalog as a single response — fields include total (integer count) and an events array of summary objects. Each summary carries enough metadata to identify events by date, category, and scoring thresholds. To drill into a specific event, pass its numeric ID (e.g. '23542') to get_event, which returns fields like title, open_at, begin_at, end_at, close_at, status, icon_url, page_url, and created_at — all datetimes in ISO 8601 format. The status integer field reflects the event's current lifecycle state.
Participant Rankings
get_event_results returns a paginated leaderboard for a given event_id. Each page returns up to 30 participants, and the pagination object surfaces current_page, next_page, and current_items so you can walk through large events. The participants array includes each entrant's rank, score, and streamer profile information. The total_participants integer gives the full headcount for a given event without needing to exhaust all pages.
Coverage and Scope
All three endpoints target REALITY broadcaster events specifically — not individual live stream sessions, viewer counts, or gift transaction records. The get_event response includes page design configuration fields alongside schedule and constraint data, making it suitable for reconstructing event display logic as well as tracking dates and statuses.
The REALITY API is a managed, monitored endpoint for reality.app — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when reality.app changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official reality.app API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display a live leaderboard widget showing streamer rankings and scores from
get_event_results - Build a notification system that alerts fans when an event's
statustransitions usingget_eventpolling - Aggregate historical event data from
list_eventsto analyze event frequency and category trends over time - Render an event detail page using
title,icon_url,page_url, and schedule fields fromget_event - Track a specific streamer's ranking movement across multiple event pages via
get_event_resultspagination - Compile a calendar view of upcoming and past REALITY events using
open_at,begin_at, andend_atdates
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does REALITY have an official developer API?+
What does `list_events` return and how many events does it cover?+
list_events returns all past and present broadcaster events in a single response — no pagination required. The response includes a total integer and an events array with summary metadata such as dates, category, and scoring thresholds. The count reflects whatever events exist on the REALITY platform at the time of the call.How does pagination work in `get_event_results`?+
pagination object in the response includes current_page, next_page, and current_items. Pass the page parameter (1-based) to step through results. If next_page is null, you have reached the final page. The total_participants field tells you the full count upfront.Does the API expose individual live stream sessions or viewer/gift data?+
list_events, event metadata via get_event, and participant rankings via get_event_results. Viewer counts, individual stream sessions, and gift or coin transaction records are not included. You can fork this API on Parse and revise it to add an endpoint targeting those data surfaces.Can I filter events by category, date range, or status directly in the API?+
list_events returns the full event catalog without server-side filtering options. Category, date, and status fields are present in the response, so client-side filtering is possible, but the API does not expose filter parameters. You can fork this API on Parse and revise it to add filtered query support.