# Agents

Research agents for automated content research

## List research agents

> List all research agents for the team. Requires Power plan or higher.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Research agents for automated content research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"agent_type":{"type":"string","enum":["local_news","content_gap","trend_research","programmatic_seo"]},"site_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","running","error"]},"schedule":{"type":"string","enum":["weekly","biweekly","monthly","manual"]},"run_count":{"type":"integer"},"last_run_at":{"type":"string","format":"date-time","nullable":true},"next_run_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/agents":{"get":{"summary":"List research agents","description":"List all research agents for the team. Requires Power plan or higher.","parameters":[{"in":"query","name":"site_id","schema":{"type":"string","format":"uuid"},"description":"Filter by site ID"}],"responses":{"200":{"description":"List of agents","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}}},"tags":["Agents"]}}}}
```

## Get an agent

> Get agent details including latest snapshot and research brief.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Research agents for automated content research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"AgentDetail":{"allOf":[{"$ref":"#/components/schemas/Agent"},{"type":"object","properties":{"config":{"type":"object","description":"Agent-type-specific configuration"},"sources":{"type":"array","items":{"type":"object"},"description":"Data sources configuration"},"latest_snapshot":{"type":"object","nullable":true,"description":"Most recent agent run snapshot with crawl stats and extracted data"},"latest_brief":{"type":"object","nullable":true,"description":"Most recent research brief with content ideas and keywords"}}}]},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"agent_type":{"type":"string","enum":["local_news","content_gap","trend_research","programmatic_seo"]},"site_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","running","error"]},"schedule":{"type":"string","enum":["weekly","biweekly","monthly","manual"]},"run_count":{"type":"integer"},"last_run_at":{"type":"string","format":"date-time","nullable":true},"next_run_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/agents/{id}":{"get":{"summary":"Get an agent","description":"Get agent details including latest snapshot and research brief.","responses":{"200":{"description":"Agent detail with latest results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDetail"}}}}},"tags":["Agents"]}}}}
```

## Trigger an agent run

> Manually trigger an agent to run immediately. Returns 409 if already running.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Research agents for automated content research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/agents/{id}/run":{"post":{"summary":"Trigger an agent run","description":"Manually trigger an agent to run immediately. Returns 409 if already running.","responses":{"200":{"description":"Agent run triggered","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"409":{"description":"Agent is already running"}},"tags":["Agents"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/rest-api/agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.