Search

GET/v1/cosmos/search1 credit

Searches Cosmos for posts matching a query and returns them with caption, media, owner and source.

01Query parameters

Name	Type	Description
queryrequired	string	Search terms, e.g. `architecture`.
cursoroptional	string	The `cursor` value of the previous answer, to get the next page. The literal `null` returns an empty end page for free.

02Pricing

1 credit per page. `cursor=null` answers an empty end page (`end_of_pagination: true`) for 0 credits, and an empty page is free too.

03Request

curl "https://api.scrapesocial.ai/v1/cosmos/search?query=architecture" \
  -H "x-api-key: $SCRAPESOCIAL_KEY"

04Responses

Real answers from the API. Lists are shortened to 2 items.

GET /v1/cosmos/search?query=architecture

{
  "success": true,
  "credits_remaining": 4980,
  "credits_charged": 1,
  "items": [
    {
      "id": 547956585,
      "url": "https://www.cosmos.so/e/547956585",
      "created_at": "2025-06-19T12:57:19.994842Z",
      "caption": "An architectural poster created using Midjourney v7.",
      "text": null,
      "title": null,
      "description": null,
      "owner": {
        "id": 2059029120,
        "username": "joris.kahl"
      },
      "source_url": "https://www.instagram.com/p/DK2wZxvMsbf/?igsh=MW9ubmc3NzRucHBkNg==",
      "source_author": {
        "username": "ai_architecture_awards",
        "full_name": "AI Architecture",
        "profile_url": "https://www.instagram.com/ai_architecture_awards",
        "avatar_url": null
      },
      "media": [
        {
          "id": "589cdf02-9abf-4d94-88ef-809734ca5444",
          "type": "StaticImage",
          "url": "https://cdn.cosmos.so/e00a12d4-1e19-45de-9649-b42e9c9f724a",
          "width": 928,
          "height": 1232,
          "ai_generated": false,
          "duration": null,
          "thumbnail_url": null,
          "video_url": null,
          "playback_url": null
        },
        {
          "id": "0e2ebb91-84fc-4700-b076-7c772289b9c7",
          "type": "StaticImage",
          "url": "https://cdn.cosmos.so/4c815d2f-c297-4bee-89f3-bdc8e952440f",
          "width": 928,
          "height": 1232,
          "ai_generated": false,
          "duration": null,
          "thumbnail_url": null,
          "video_url": null,
          "playback_url": null
        }
      ],
      "price": null,
      "brand": null
    },
    {
      "id": 1608649362,
      "url": "https://www.cosmos.so/e/1608649362",
      "created_at": "2025-03-04T23:13:59.334456Z",
      "caption": "Habitat 67, a Brutalist housing complex by Moshe Safdie, was built for Montreal's Expo 67.",
      "text": null,
      "title": null,
      "description": null,
      "owner": null,
      "source_url": "https://www.instagram.com/p/DGuzvRVsZse/",
      "source_author": {
        "username": "archdaily",
        "full_name": "Architecture 🏠",
        "profile_url": "https://www.instagram.com/archdaily",
        "avatar_url": null
      },
      "media": [
        {
          "id": "ebae3229-6112-47a3-9e9d-1a8a66e6924c",
          "type": "StaticImage",
          "url": "https://cdn.cosmos.so/617e1f3d-1ba8-4586-abcf-e78d396b1837",
          "width": 1080,
          "height": 1350,
          "ai_generated": false,
          "duration": null,
          "thumbnail_url": null,
          "video_url": null,
          "playback_url": null
        }
      ],
      "price": null,
      "brand": null
    }
  ],
  "cursor": "cursor://recsys/search?user_id=0&profile=search__dual70_nouser_recql&query=architecture&last=39&count=500",
  "has_more": true,
  "result_count": 500
}

Common to every endpoint

Any route can answer these: a missing or wrong key, no credits left, the platform not answering, or a failure on our side. None of them costs credits.

GET /v1/cosmos/profile?handle=design

{
  "success": false,
  "message": "Invalid API key"
}

05Notes

Posts are in `items` (40 per page), with `cursor`, `has_more` and `result_count`. `result_count` is the size of the search window that can be paged through, not an exact number of matches. Pass `cursor` back for the next page. Cosmos searches by meaning, so even an unusual query usually returns posts; a search that finds nothing is a 200 with an empty list for 0 credits.

06Errors & credits

Every error has success: false, a real HTTP status and costs no credits.

400missing_parameter
A required parameter is missing or invalid.
403private_account
The account is private or age-restricted.
404not_found
No such account.
503upstream_error
The platform did not answer; retry shortly.