Create a tracker
POST
/v1/view-tracker/trackersStarts tracking a profile or a single post. The first refresh runs right away, then every interval_minutes, and every reading is kept. The type is inferred from the URL, so a post URL makes a post tracker.
- Creating is free, but the first refresh starts immediately and costs 1 credit, like every refresh after it.
- The tracker comes back with latest set to null. Post trackers usually fill within seconds and profile trackers within a minute or two: wait for the tracker.refreshed webhook, or poll GET /v1/view-tracker/trackers/{id} every few seconds until latest is not null.
- If the first refresh fails, latest stays null and tracker.refresh_failed fires. After 3 failures in a row the tracker pauses with status paused_failing.
- A type is inferred from the URL: Instagram /p/, /tv/ and /reel/ links, YouTube watch links and TikTok /video/ links are posts. Send type only to override a URL we cannot classify.
- If you run out of credits the tracker pauses with status paused_no_credits and resumes by itself when credits arrive.
- Credits:
- 0 now, 1 credit per refresh
- Rate limit:
- Tracker writes tier, 2/s and 60/min
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| url | body | string | No | Profile or post URL. Instagram, YouTube, TikTok and Twitter are supported. Send url, or handle with platform. |
| type | body | string | No | Force the target type when the URL is ambiguous.profilepost |
| platform | body | string | No | Required with handle. With a url it must match the url's platform, or the request is a 400.instagramyoutubetiktoktwitter |
| handle | body | string | No | Profile handle, instead of url. Needs platform; a handle without platform is a 400. |
| interval_minutes | body | integer | No | Minutes between refreshes. Each refresh costs 1 credit, so this sets the monthly cost: 43,200 divided by the interval. 10 to 10080. Common values: 10, 30, 60, 180, 720, 1440.default 1440 |
| max_posts | body | integer | No | How many of the newest posts a profile tracker keeps up to date. Ignored for post trackers. It does not change the price: a refresh is 1 credit at any depth.default 10050100200 |
Request
curl
curl -X POST "https://api.crayo.ai/v1/view-tracker/trackers" \
-H "Authorization: Bearer $CRAYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.instagram.com/mornings.with.ada/",
"interval_minutes": 1440,
"max_posts": 100
}'Response
200 application/json
{
"success": true,
"tracker": {
"id": "cm9t3k1r20001abcd",
"type": "profile",
"platform": "instagram",
"url": "https://www.instagram.com/mornings.with.ada/",
"handle": "mornings.with.ada",
"status": "active",
"interval_minutes": 1440,
"max_posts": 100,
"next_refresh_at": "2026-10-15T09:12:44.000Z",
"behind": false,
"last_refreshed_at": null,
"credits_per_month": 30,
"credits_spent": 0,
"refresh_count": 0,
"created_at": "2026-10-02T14:03:19.000Z",
"goal_followers": 100000,
"goal_by": "2026-12-31T00:00:00.000Z",
"group_name": "Clients",
"alert_kinds": [
"viral",
"milestone"
],
"latest": null
}
}Errors
- 400VALIDATION_ERRORThe URL does not parse, handle was sent without platform, platform does not match the url, the cadence is outside 10 to 10,080 minutes, or the platform is Facebook (raw mode only).
- 400UNKNOWN_FIELDThe body carries a field this endpoint does not define.
- 401MISSING_API_KEYNo Authorization header was sent, or it does not carry a crayo_sk_ key.
- 401UNAUTHORIZEDThe key sent is malformed, expired, or revoked.
- 402INSUFFICIENT_CREDITSYou have no tracker credits to run the first refresh. Buy a pack or wait for your plan to renew.
- 409TRACKER_EXISTSYou already track this target. error.tracker_id is the existing tracker's id.
- 409TRACKER_LIMIT_REACHEDYou are at your active target limit (500 by default). The error carries active_trackers and cap. Ask in Discord (crayo.ai/discord) or email support@crayo.ai and we will raise it.
- 429CONCURRENT_REQUESTAnother create or batch request for your account is still running. Await it, then retry.
- 429RATE_LIMITEDOver this tier's limit, counted per account. Raw lookups also answer this when 10 are already in flight. Wait the number of seconds in the Retry-After header.
- 429RATE_LIMITEDOver the rate limit. Wait Retry-After seconds.
- 500SERVER_ERRORSomething failed on our side. Retry with backoff.