---
title: "Get a compact, agent-ready summary for an agent"
method: GET
path: "/v1/agents/{id}/summary"
tags: ["Content Research Agents"]
---

# Get a compact, agent-ready summary for an agent

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

## Request

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

One free call that returns an agent’s whole picture: config + finalized/progress state, the latest run’s headline counts, cheap corpus counts, the top creators and trend themes, and the latest AI-analysis highlight. A convenience digest — use the dedicated videos/creators/trends/analysis endpoints for full, paginated data. Pieces still processing (analysis / trends / outliers) come back null/empty rather than failing the whole summary.

## Path parameters

- `id` string, required

## Response `200`

Agent summary

- AgentSummaryResponseDto
  - `data` AgentSummaryDataDto, required
    - `agent_id` string, uuid, required
    - `agent_name` string, nullable
    - `is_recurring` boolean, required
    - `finalized` boolean, required: True when the latest run (scrape + AI analysis) is fully settled.
    - `progress_pct` number, nullable
    - `stage` 'collecting' | 'analyzing' | 'finalizing' | 'completed', nullable
    - `eta_seconds` number, nullable
    - `run` AgentSummaryRunDto
      - `status` 'pending' | 'processing' | 'completed' | 'partial_failure' | 'failed', nullable
      - `started_at` string, nullable
      - `completed_at` string, nullable
      - `total_videos` number, nullable: Videos the latest run touched (inserted + updated). Null when the run reports neither.
      - `videos_linked` number, nullable: Videos linked into this agent's corpus by the latest run.
      - `platform_counts` AgentSummaryPlatformCountsDto, required
        - `youtube` number, nullable
        - `tiktok` number, nullable
        - `instagram` number, nullable
      - `outliers_identified` number, nullable
    - `counts` AgentSummaryCountsDto, required
      - `videos` number, nullable: Total videos in the agent's corpus (cumulative), when known cheaply.
      - `slideshows` number, nullable
      - `sounds` number, nullable: Not cheaply available on this digest — always null for now.
      - `creators` number, nullable: Outlier creators known for the agent, when cheaply available.
    - `top_creators` AgentSummaryTopCreatorDto[], required: Up to 5 top creators by weighted outlier score. Empty if none.
      - `username` string, nullable: Creator handle, derived from the creator's profile URL.
      - `platform` string, nullable
      - `followers` number, nullable
      - `weighted_score` number, nullable: Size-weighted outlier score (Virality Score).
    - `top_trends` AgentSummaryTopTrendDto[], required: Up to 5 trend themes from the latest completed analysis. Empty if not ready.
      - `name` string, required
      - `stable_key` string, nullable
      - `status` 'new' | 'rising' | 'steady' | 'fading', nullable
    - `analysis_summary` string, nullable: Short human-readable highlight from the latest AI analysis. Null if none yet.
    - `generated_at` string, required: ISO timestamp this digest was built.

## 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)