Skip to navigation

Finding media

There are two ways to get an account’s posts. Check the index first. Fetch live posts when the account is not there.

POST /media and GET /account/posts

POST /mediaGET /account/posts
What it readsPosts already in the Spyglass indexPosts fetched and processed during the request
Account must be indexedYesNo. A handle or Facebook Ad Library id is enough
How long it takesTypically under 10 secondsAbout 10–30 seconds. Longer when limit spans more than one source page
What you passaccountId from search, or a query across the indexExactly one of igUsername, tiktokUsername, or facebookAdLibraryId
limitDefault 100, max 2000Default 20, max 120
Price1 credit per creative, minimum 11 credit per post, minimum 1

POST /media is the path for creatives Spyglass has already processed: hooks, categories, and performance are on the rows. GET /account/posts is the path when you know the account and it is not in the index yet. Both charge 1 credit per row returned. A call that returns no posts still costs 1 credit.

Resolve the account, then search the index

  1. Resolve the account with POST /brands or POST /creators. Pass a name, handle, or short query. If you already have a platform id or handle, GET /account/{id} reads that account directly.
  2. Pass the returned id as accountId to POST /media. Omit query when you want that account’s library. Add query only when you want one theme inside that account.
  3. If search returns no account, or POST /media has no rows for it, and you know the Instagram handle, TikTok handle, or Facebook Ad Library page id, call GET /account/posts.

A topic search skips the account step. POST /media with query and no accountId searches the whole index.

Live posts

GET /account/posts does not require the brand to be indexed. Spyglass fetches the posts from Instagram, TikTok, or the Facebook Ad Library and processes them on the request. Plan for about 10–30 seconds. For Instagram, postType is posts (default) or reels. reels cannot be combined with tagged=true.

The same request starts indexing the rest of the brand’s posts. Once that finishes, later lookups can use POST /media and come back faster.

A limit above one source page takes longer, because each page is a separate fetch:

SourcePosts per source page
Instagram12
Instagram tagged (tagged=true)up to 10
TikTok10
Facebook Ad Library30

limit defaults to 20 and maxes at 120. Sort and identifier rules are in Conventions.

When you will query the account again

A live GET /account/posts call already starts indexing the rest of the brand’s posts. POST /account/index is the explicit way to add the account when you also want insights, campaigns, and landing pages. Poll GET /account/{id}/index-status until it is ready, then use POST /media.