Cosmos

Search Cosmos posts

Search Cosmos posts by meaning, with their media and sources.

GET/v1/cosmos/search/posts
x-api-keystringheader

API key (`sfk_...`)

Parameters
2
querystringrequiredquery

Words to search for, up to 100 characters. Cosmos searches by meaning, so related posts match too.

min 1 chars · max 100 chars

cursorstringoptionalquery

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

Response fields
49

Endpoint-specific response payload.

datalookupStatus
string

Always `found`: no match is an empty list.

one of: found, not_found

dataquery
string

The search text that was asked for.

The best-matching posts, best first, about 40 a page.

dataposts[]id
string

Cosmos post (element) id.

dataposts[]url
string

Post page.

dataposts[]createdAt
stringnullable

When it was saved to Cosmos.

dataposts[]caption
stringnullable

The description Cosmos wrote for the post.

The post's media, the main one first.

dataposts[]media[]type
string

`image`, `video` or `gif`.

one of: image, video, gif, unknown

dataposts[]media[]url
stringnullable

The file: the image, or the video's MP4.

dataposts[]media[]thumbnailUrl
stringnullable

A still for a video or gif.

dataposts[]media[]width
integernullable

Width in pixels.

dataposts[]media[]height
integernullable

Height in pixels.

dataposts[]media[]durationSeconds
numbernullable

Length of a video in seconds.

dataposts[]media[]isAiGenerated
booleannullable

True when Cosmos marks the image as AI-generated.

dataposts[]media[]isSafe
booleannullable

False when Cosmos marks the media not safe for work.

The Cosmos user who saved it.

dataposts[]savedByid
stringnullable

Cosmos user id.

dataposts[]savedByhandle
string

Username, as in cosmos.so/{handle}.

dataposts[]savedBydisplayName
stringnullable

Full name.

dataposts[]savedByavatarUrl
stringnullable

Profile picture.

dataposts[]savedByisVerified
booleannullable

True when Cosmos verified the profile.

dataposts[]savedByurl
string

Profile page.

dataposts[]collectionId
stringnullable

The collection it was first saved to.

dataposts[]sourceUrl
stringnullable

Where it came from, such as an Instagram or Pinterest post.

Who made it, at the source.

dataposts[]sourceAuthorhandle
stringnullable

Username at the source.

dataposts[]sourceAuthorname
stringnullable

Name at the source.

dataposts[]sourceAuthorurl
stringnullable

Profile at the source.

dataposts[]isFeatured
booleannullable

True when Cosmos features the post.

The product, when the post is a shop item; else null.

dataposts[]productname
stringnullable

Product name.

dataposts[]productbrand
stringnullable

Brand.

dataposts[]productdescription
stringnullable

Product description.

dataposts[]productprice
numbernullable

Price, the sale price when Cosmos shows one.

dataposts[]productcurrency
stringnullable

ISO 4217 currency of `price`, such as `USD`.

dataposts[]productavailability
stringnullable

Stock state, such as `in_stock` or `out_of_stock`.

datatotal
integernullable

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.

datapagehasMore
boolean

Whether another page is available.

datapagenextCursor
stringnullable

Cursor to pass in the next request when more pages exist; null on the last page.

datapagetruncated
boolean

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.

metarequestId
string

Unique request identifier for tracing this API call.

min 1 chars

metacreditsCharged
integer

Credits charged for this request.

≥ 0

metaversion
string

Public API version that served the response.

one of: v1

metastale
booleanoptional

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

metafetchedAt
stringoptional

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.