Posts

Get a post's thumbnail from its URL

Look up a post's cover image from the post's URL, before any campaign exists for it.

This is for the moment a brand pastes a URL into a form. It reads the post, returns the cover image, and — because it has to read the post to find one — also confirms the URL points at a real, readable post. Nothing is created or stored, so it is safe to call on every paste and leaves nothing behind if the brand abandons the form.

Call it before POST /admin/campaigns. GET /admin/challenges/{challengeId}/metrics also returns a thumbnailUrl, but only once the campaign exists, which is too late for a form that has not been saved yet.

Which URLs are accepted. Instagram posts (/p/...) and reels (/reel/...), and TikTok videos (/@user/video/...). Share tags and other extra query parameters are ignored — canonicalUrl in the response is the cleaned-up form, and it is what to send as the challenge's targetUrl when the campaign is finally created. Anything else is rejected with 422 VALIDATION_ERROR without reading anything.

thumbnailUrl expires. It is a signed link that stops working within days, so download the image when you receive it instead of storing the URL. A post that is readable but publishes no usable image comes back as thumbnailUrl: null with a 200 — that is a post without a cover, not a failure.

How long it takes. Usually about a second. A small share of posts have to be read a slower way and can take up to 40 seconds, so give the request a generous client timeout rather than retrying one that is still running. An Instagram URL whose post has been deleted takes the slower way too — the deletion is confirmed with a second provider before 404 POST_NOT_FOUND is returned — so a slow answer does not by itself mean the URL is bad.

Limits. Ten lookups per post per five minutes, and 100 per caller per minute. Both are guards against a loop rather than a quota: one paste per campaign never comes near them, and there is room to retry a paste that failed.

GET

/admin/posts/thumbnail

Send

Headers

Query

Authorization

Query Parameters

curl -X GET "//admin/posts/thumbnail?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FDcikt3sEvp8" \
  -H "Authorization: Bearer <token>"

{
  "data": {
    "platform": "instagram",
    "contentType": "post",
    "contentId": "Dcikt3sEvp8",
    "canonicalUrl": "https://www.instagram.com/p/Dcikt3sEvp8/",
    "thumbnailUrl": "https://scontent.cdninstagram.com/v/t51.82787-15/792667282.jpg?stp=dst-jpg&oh=00_AQ&oe=6A9F2C99"
  }
}