POST /v1/resolve

Give it any supported social URL. It tells you what the URL points at and returns the normalized object, so you do not need to know the platform in advance.

When to use it

Use resolve when a URL arrives from somewhere you do not control — a customer pasting a link, a spreadsheet import, a form field. It works out the platform and resource type for you and returns the object in one round trip.

If you already know you have a TikTok profile, call /v1/profile directly. Same cost, one less indirection.

Request

POST /v1/resolve
Content-Type: application/json
Authorization: Bearer sv_live_…

Field	Type	Required	Notes
`url`	string	yes	Any supported profile or post URL
`freshness`	string	no	`cached` (default) or `fresh`

Cost: Basic — 1 credit. Free on a cache hit.

Supported URL shapes

Platform	Profile	Post
TikTok	`tiktok.com/@handle`	`tiktok.com/@handle/video/ID`, `/photo/ID`
Instagram	`instagram.com/handle/`	`instagram.com/p/CODE/`, `/reel/CODE/`
YouTube	`youtube.com/@handle`, `/channel/ID`	`youtube.com/watch?v=ID`, `/shorts/ID`, `youtu.be/ID`

Short links (vm.tiktok.com, vt.tiktok.com) are recognised and expanded. Expansion is on us — it does not cost you an extra credit.

Example

curl https://api.sourcevine.io/v1/resolve \
  -H "Authorization: Bearer $SOURCEVINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@atlas.makes/video/7042118893001"}'

{
  "id": "sd_post_1c7be04a92f3d558",
  "platform": "tiktok",
  "resource_type": "post",
  "platform_resource_id": "7042118893001",
  "author": { "platform_resource_id": "6789432100", "username": "atlas.makes" },
  "url": "https://www.tiktok.com/@atlas.makes/video/7042118893001",
  "caption": "the jig that finally worked",
  "media_type": "video",
  "published_at": "2026-08-20T09:00:00Z",
  "metrics": {
    "views": 412000, "likes": 38400, "comments": 921,
    "shares": 2140, "saves": 6630
  },
  "availability": { "status": "available", "reason": null },
  "source_timestamp": "2026-08-27T09:40:11Z",
  "fetched_at": "2026-08-27T09:41:02Z",
  "cache_age_seconds": 288,
  "freshness": "cached"
}

Branch on resource_type to know what you got:

obj = r.json()
if obj["resource_type"] == "profile":
    followers = obj["metrics"]["followers"]
elif obj["resource_type"] == "post":
    views = obj["metrics"]["views"]

Errors

An unsupported host or an unparseable path returns 400 with code unparseable_url, and is not charged — the URL is rejected before any upstream call. A URL we can parse but cannot retrieve returns 200 with an availability.status of not_found, private or unavailable; see errors & availability.

Last updated 27 August 2026