Collections API

The Collections API lets you create and manage crawl tasks — the scheduled jobs that gather posts, comments, and profiles from connected platforms — and read the results they produce.

Overview

A crawl task defines what to collect (keywords, platforms, filters) and when. Each run produces crawl results: individual matched items that Anvil scores and can promote to leads. All endpoints are authenticated with a Bearer API key and scoped to the calling tenant.

List Crawl Tasks

curl -X GET https://api.anvilhk.com/v1/crawl-tasks \
  -H "Authorization: Bearer anv_live_sk_49kPz9..." \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    { "id": "task_8f2", "name": "LED buyers — TikTok", "status": "RUNNING", "platforms": ["TIKTOK"], "resultCount": 412 }
  ],
  "meta": { "total": 7, "cursor": "eyJp...", "hasMore": false }
}

Create a Crawl Task

Supply the platforms, keywords, and a schedule. The schedule can be ONCE, HOURLY, DAILY, or a cron expression.

curl -X POST https://api.anvilhk.com/v1/crawl-tasks \
  -H "Authorization: Bearer anv_live_sk_49kPz9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LED buyers — TikTok",
    "platforms": ["TIKTOK", "INSTAGRAM"],
    "keywords": ["LED panel supplier", "wholesale LED"],
    "schedule": "DAILY",
    "filters": { "minFollowers": 500, "language": "en" }
  }'

The task is created in PENDING and transitions to RUNNING on its first execution.

Retrieve Results

Fetch the items a task has collected. Results are cursor-paginated and include the AI intent score.

curl -X GET "https://api.anvilhk.com/v1/crawl-results?taskId=task_8f2&minScore=70" \
  -H "Authorization: Bearer anv_live_sk_49kPz9..."

{
  "success": true,
  "data": [
    { "id": "res_01a", "platform": "TIKTOK", "author": "@buyer_co", "score": 84, "promotedLeadId": "lead_77c" }
  ],
  "meta": { "total": 412, "cursor": "eyJp...", "hasMore": true }
}

Task Lifecycle

Control a running task with the lifecycle endpoints:

Statuses are PENDING, RUNNING, PAUSED, COMPLETED, FAILED, and SCHEDULED.

Errors

The API uses the standard envelope. A failed request returns success: false and an error object — for example, a 403 when your key lacks the required scope:

{
  "success": false,
  "error": { "code": "FORBIDDEN", "message": "API key is missing the read:collections scope" }
}

See [Rate Limits](/docs/api-reference/rate-limits) for throughput caps — crawl-task creation counts against a stricter per-hour bucket than read endpoints.