Search Cosmos posts
Search Cosmos posts by meaning, with their media and sources.
Headers
Get your API keyAPI key (`sfk_...`)
Words to search for, up to 100 characters. Cosmos searches by meaning, so related posts match too.
min 1 chars · max 100 chars
Pass `page.nextCursor` from the previous response to get the next page. It only works with the same handle, collection or query.
min 1 chars · max 4096 chars
Endpoint-specific response payload.
Always `found`: no match is an empty list.
one of: found, not_found
The search text that was asked for.
The best-matching posts, best first, about 40 a page.
Cosmos post (element) id.
Post page.
When it was saved to Cosmos.
The description Cosmos wrote for the post.
The post's media, the main one first.
`image`, `video` or `gif`.
one of: image, video, gif, unknown
The file: the image, or the video's MP4.
A still for a video or gif.
Width in pixels.
Height in pixels.
Length of a video in seconds.
True when Cosmos marks the image as AI-generated.
False when Cosmos marks the media not safe for work.
The Cosmos user who saved it.
Cosmos user id.
Username, as in cosmos.so/{handle}.
Full name.
Profile picture.
True when Cosmos verified the profile.
Profile page.
The collection it was first saved to.
Where it came from, such as an Instagram or Pinterest post.
Who made it, at the source.
Username at the source.
Name at the source.
Profile at the source.
True when Cosmos features the post.
The product, when the post is a shop item; else null.
Product name.
Brand.
Product description.
Price, the sale price when Cosmos shows one.
ISO 4217 currency of `price`, such as `USD`.
Stock state, such as `in_stock` or `out_of_stock`.
How many posts Cosmos counts as matching, up to 500. It can exceed what Cosmos lets anyone read: paging may end earlier (484 of 501 for `photography`).
Pagination state for the current page.
Whether another page is available.
Cursor to pass in the next request when more pages exist; null on the last page.
True when the list stops here before its end: more rows exist (see `total`) but no further page can be read.
Metadata describing the request and billing outcome.
Unique request identifier for tracing this API call.
min 1 chars
Credits charged for this request.
≥ 0
Public API version that served the response.
one of: v1
Present, and `true`, only when the source couldn't be reached and this is the last good answer for the same request instead, up to 24 hours old. Absent on every live answer.
one of: true
When a stale answer (`stale: true`) was originally fetched (ISO 8601, UTC). Absent on every live answer.
Code example
curl "https://api.socialfetch.dev/v1/cosmos/search/posts?query=architecture" \
-H "x-api-key: YOUR_API_KEY"Responses
Matching Cosmos posts.