> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/cosmos>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/cosmos.mdx>

---

# Cosmos API. Curators, collections and saves as JSON.

Look up a Cosmos curator, read their latest saves and collections, open any post or collection, and search images by describing them.

- Profiles + collections
- Search by meaning
- 1 credit per request

`GET /v1/cosmos/profiles/{handle}` returns a Cosmos curator: name, bio, avatar, website, social links, membership, verification and counts of posts, collections, followers and following. `/posts` and `/collections` under it list the latest saves and the public collections.

A post (`GET /v1/cosmos/posts?url=`) carries its image or video with its size, the caption Cosmos wrote, when it was saved, who saved it and where it came from. A collection (`GET /v1/cosmos/collections?url=`) carries its owner, cover, size and followers, and `/collections/posts` lists what is in it. Search finds posts by meaning, in any language. Every answer is JSON in the `{ data, meta }` envelope with `data.lookupStatus`; lists carry `total`. A miss comes back as `lookupStatus: not_found`, not as an HTTP error.

## What you can get

- Curator profile with bio, website, social links, membership and counts.
- A curator's latest posts and public collections, with totals.
- Single posts with media, caption, saver and source.
- Single collections with owner, cover, size and followers, and their latest posts.
- Post search by meaning, in any language.

## Cosmos endpoints

| Endpoint | Request | Credits | Docs |
| --- | --- | --- | --- |
| Profile | GET /v1/cosmos/profiles/{handle} | 1 credit Failed requests are free Found and not-found answers are both charged | [docs](https://www.socialfetch.dev/docs/api/v1/cosmos/profiles/handle/get) |
| Profile posts | GET /v1/cosmos/profiles/{handle}/posts | 1 credit Failed requests are free Found and not-found answers are both charged | [docs](https://www.socialfetch.dev/docs/api/v1/cosmos/profiles/handle/posts/get) |
| Profile collections | GET /v1/cosmos/profiles/{handle}/collections | 1 credit Failed requests are free Found and not-found answers are both charged | [docs](https://www.socialfetch.dev/docs/api/v1/cosmos/profiles/handle/collections/get) |
| Post | GET /v1/cosmos/posts | 1 credit Failed requests are free Found and not-found answers are both charged | [docs](https://www.socialfetch.dev/docs/api/v1/cosmos/posts/get) |
| Collection | GET /v1/cosmos/collections | 1 credit Failed requests are free Found and not-found answers are both charged | [docs](https://www.socialfetch.dev/docs/api/v1/cosmos/collections/get) |
| Collection posts | GET /v1/cosmos/collections/posts | 1 credit Failed requests are free Found and not-found answers are both charged | [docs](https://www.socialfetch.dev/docs/api/v1/cosmos/collections/posts/get) |
| Search posts | GET /v1/cosmos/search/posts | 1 credit Failed requests are free Found and not-found answers are both charged | [docs](https://www.socialfetch.dev/docs/api/v1/cosmos/search/posts/get) |

## How to start

1. **Create an API key.** Sign up at Social Fetch and copy a key (`sfk_…`). New accounts get 100 free credits, enough to try every route on a few curators.
2. **Pick the curator, post or collection.** Use the username, for example `GET /v1/cosmos/profiles/joris.kahl`, or a post or collection link. Send `x-api-key` on every request.
3. **Branch on the answer.** Check `data.lookupStatus` before you store a row, compare a list with its `total`, and bill from `meta.creditsCharged`.

## Pricing

Each Cosmos route charges a flat credit amount per completed request, shown on every endpoint page. Credits never expire on pay-as-you-go packs, and `meta.creditsCharged` on every response is the billing source of truth.

## Compared with the official API

Social Fetch gives every Cosmos route one JSON shape: ISO 8601 UTC timestamps, numeric counts, ids as strings, absolute links and typed `lookupStatus` responses. You do not need a Cosmos account, an app registration or a user session.

## FAQ

### What Cosmos data can I get from the API?

Curator profiles, their latest posts and public collections, single posts and collections, the latest posts of a collection, and post search.

### How do I name a Cosmos curator?

Use the username from the profile link, cosmos.so/{username}, for example joris.kahl. An unknown username returns lookupStatus: not_found.

### Can I page through all of a curator's posts?

Not yet. Without signing in Cosmos shows the latest page of each list, so the lists return that page and a total of how many exist.

### What is a collection?

A board a curator saves posts into, sometimes with collaborators and sub-collections. Its link is cosmos.so/{username}/{collection}.

### How does search work?

Cosmos searches by meaning: describe what you want, in any language, and it returns the closest posts, about 40 a request.

### Do you return the images themselves?

No. Each post links to its image or video file and to the source it was saved from; download the file if you need it.

### How much does the Cosmos API cost?

Every Cosmos route charges a flat amount per completed request, shown on each endpoint page. A found or not-found answer is a completed request and costs that amount; invalid requests and errors are free. Check meta.creditsCharged on every response. New accounts start with 100 free credits.

## Related

- [Cosmos Profile API](https://www.socialfetch.dev/platforms/cosmos/profiles-handle): Bio, links and counts (`GET /v1/cosmos/profiles/{handle}`).
- [Cosmos Collection API](https://www.socialfetch.dev/platforms/cosmos/collections): One collection by link (`GET /v1/cosmos/collections`).
- [Cosmos Post API](https://www.socialfetch.dev/platforms/cosmos/posts): One post with media and source (`GET /v1/cosmos/posts`).
- [Cosmos Search API](https://www.socialfetch.dev/platforms/cosmos/search-posts): Posts by meaning (`GET /v1/cosmos/search/posts`).
- [Ask in plain English](https://www.socialfetch.dev/ask): Route a natural-language Cosmos question to the matching operation.
- [Hosted MCP](https://www.socialfetch.dev/mcp): Call Cosmos tools from Cursor or Claude with the same credit metering as REST.
