# Build a research workflow

Canonical URL: https://docs.viralspy.com/docs/guides/agent



The strongest workflow separates retrieval from synthesis.

## 1. Retrieve narrowly [#1-retrieve-narrowly]

Search with a clear subject and a small `limit`. Use ranked feeds when you need discovery without a text query. Add ad or hook filters only when they express a real constraint.

## 2. Resolve canonical entities [#2-resolve-canonical-entities]

Save video aweme IDs, creator UIDs, and advertiser UUIDs. Handles and display names can change or collide. Canonical IDs keep bookmarks, caches, and joins stable.

## 3. Inspect evidence [#3-inspect-evidence]

Fetch detail records and representative videos. Record the time window and URLs used. ViralSpy classifications can guide research, but a model-assisted label should not be presented as a legal determination.

## 4. Synthesize once [#4-synthesize-once]

Call the analyst after you have a focused question. Supply relevant context, use an idempotency key, and retain the final evidence-bearing result. This consumes one shared organisation request; primitive search does not.

```js
const idempotencyKey = crypto.randomUUID();
const response = await fetch('https://api.viralspy.com/v1/agent/answers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIRALSPY_API_KEY}`,
    Accept: 'text/event-stream',
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    question: 'Which three hook mechanics recur across these examples?',
    context: 'Video IDs: 755…, 754…, 753…',
  }),
});
```

If the connection drops, retry with the same key or fetch `/v1/agent/answers/{id}`. Do not submit a new key for the same work.

SSE is the default and recommended mode for multi-minute analysis. Set `Accept: application/json` only when your HTTP client is configured to wait for the complete answer; idempotency and status polling still apply.