---
title: "List breaking events detected in an agent’s topic"
method: GET
path: "/v1/agents/{id}/events"
tags: ["Content Research Agents"]
---

# List breaking events detected in an agent’s topic

`GET /v1/agents/{id}/events`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/agents/{id}/events`
- Auth: HTTP bearer

Breaking stories/events the agent’s event-awareness engine has detected in its niche — a death, record, launch, controversy, or moment the space is talking about. Active (confirmed, unexpired) events come first, most salient first. Each event carries a `title`, `summary`, `salience` (0–10), lifecycle `status` (candidate / confirmed / dismissed / expired), the timely `keywords` the agent added for it, and `evidence` (top corroborating videos/results). Only recurring agents with event awareness produce events. Free.

## Path parameters

- `id` string, required

## Query parameters

- `limit` number

## Response `200`

Detected events

- AgentEventsResponseDto
  - `data` AgentEventsDataDto, required
    - `agent_id` string, uuid, required
    - `count` number, required
    - `events` AgentEventDto[], required
      - `id` string, uuid, required
      - `title` string, required: Short headline naming the event and its subject.
      - `summary` string, nullable: One-line summary of what happened and roughly when.
      - `source` 'corpus_burst' | 'news_scan', required: How the event was detected: `corpus_burst` (a spike in the agent’s own collected videos) or `news_scan` (a news probe confirmed by fresh platform content).
      - `salience` number, required: Importance 0–10 (10 = defines the niche this week). Events below the reporting threshold are not surfaced.
      - `status` 'candidate' | 'confirmed' | 'dismissed' | 'expired', required: Lifecycle: `candidate` (detected, awaiting corroboration), `confirmed` (active), `dismissed` (rejected), `expired` (past its TTL).
      - `keywords` string[], required: The timely search keywords the agent derived for this event (proper-noun phrases a creator would search).
      - `evidence` AgentEventEvidenceItemDto[], required: Top corroborating evidence — videos/results that back the event, each with `url`, `views`, and `description` when available.
        - `url` string, nullable: Source URL for this piece of evidence (a corroborating video/article), when the detection source carries one. Null for corpus-derived evidence.
        - `views` number, nullable: View count for the evidence video, when known.
        - `description` string, nullable: Short description / title of the evidence item.
      - `detected_at` string, required: When the event was first detected.
      - `confirmed_at` string, nullable: When the event was confirmed active. Null while a candidate.
      - `expires_at` string, nullable: When the event expires (TTL). Null if open-ended.

## Other responses

- `401`: Missing or invalid API key (`missing_api_key` / `invalid_api_key`)
- `404`: Agent not found
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)