---
title: "Trigger on-demand post collection for a tracked creator"
method: POST
path: "/v1/tracking/creators/{id}/posts/collect"
tags: ["Tracking"]
---

# Trigger on-demand post collection for a tracked creator

`POST /v1/tracking/creators/{id}/posts/collect`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/tracking/creators/{id}/posts/collect`
- Auth: HTTP bearer

Starts an async deep video collection job. Charged per depth tier: standard (up to 50 videos, $0.50), deep (up to 200 videos, $1.00), full (up to 500 videos, $2.00). A collection that finds no posts, or fails, is refunded (credits_refunded on the collection status). Returns 409 when the creator's tracking has failed (the collection would hit the same upstream wall); pass `{ "force": true }` to run it anyway.

## Path parameters

- `id` string, required

## Request body

- V1CollectCreatorPostsDto
  - `depth` 'standard' | 'deep' | 'full': Collection depth tier. Determines max videos fetched and credit cost. standard=50 videos, deep=200 videos, full=500 videos.
  - `force` boolean: Run the collection even though the creator's most recent tracking cycle failed (otherwise 409). A collection that still finds no posts is refunded.

## Response `202`

Collection job started

- CollectPostsResponseDto
  - `data` CollectPostsResultDto, required
    - `collection_id` string, required
    - `status` 'processing' | 'completed' | 'failed', required
    - `depth` 'standard' | 'deep' | 'full', required
    - `max_videos` number, required
    - `credits_reserved` number, required: Credits charged for this collection, billed once when the job is accepted (reflected in the X-Cost / X-Credits-Used response headers). Not charged when a collection is already in progress (409).

## Other responses

- `401`: Unauthorized - missing or invalid API key
- `402`: Insufficient credits
- `404`: Tracked creator not found
- `409`: Collection already in progress, or tracking unhealthy (the most recent tracking cycle failed; pass `force: true` to override).
- `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)