Search Cosmos elements

Try in Playground

Search for visual references by keyword and retrieve element content, media, product metadata and source attribution. Choose a page size and continue with the returned cursor.

GET/v1/cosmos/searchx-api-key

Headers

Get your API key

x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Query parameters

querystringrequiredquery

Required search text, 1 to 300 characters after trimming; control characters are rejected.

min 1 chars · max 300 chars

Exampledesign references

cursorstringquery

Opaque continuation for another page, or null. Supply it as the cursor request parameter with the same endpoint and inputs. Request cursors contain 1 to 4,096 characters and no control characters.

min 1 chars · max 4096 chars

limitstringquery

Optional requested page size, 1 to 40; default 40.

Example20

Response fields

requestIdstring

Request correlation UUID.

Source request attempts, decoded bytes and elapsed milliseconds.

accounting.upstreamRequestsinteger

Number of upstream request attempts.

≥ 0

accounting.responseBytesinteger

Decoded source bytes read during this request.

≥ 0

accounting.durationMsnumber

Elapsed request time in milliseconds.

≥ 0

successboolean

True when usable data is returned; inspect status and coverage.

statusenum

success or partial for usable data; failed or challenged for a failure response.

one of: success, partial

sourceUrlstring

Canonical Cosmos URL for the requested profile, element, collection or search.

absolute HTTPS URL

fetchedAtstring

UTC retrieval timestamp.

Returned-result coverage and extraction warnings.

coverage.sourcestring

Public Cosmos API data.

coverage.completeboolean

Whether the returned result has no reported omissions.

coverage.warningsstring[]

Warnings explaining partial results or truncated fields.

cursorstringnullable

Opaque continuation for another page, or null. Supply it as the cursor request parameter with the same endpoint and inputs. Request cursors contain 1 to 4,096 characters and no control characters.

has_moreboolean

Whether the returned cursor continues to another result page.

end_of_paginationbooleanoptional

True for the worker’s terminal response when the cursor request parameter is the literal string null; omitted on ordinary source result pages.

Returned records in source order.

up to 40 items

items.idinteger

Numeric Cosmos element ID.

≥ 0

items.urlstring

Canonical Cosmos element URL.

absolute HTTPS URL

items.created_atstringnullable

Published creation timestamp, or null.

items.captionstringnullable

Published element caption, or null.

items.textstringnullable

Published text content, or null.

items.titlestringnullable

Published title, or null.

items.descriptionstringnullable

Published description, or null.

Public identity of the Cosmos account that owns the element, or null when unavailable.

items.owner.idinteger

Numeric Cosmos owner ID.

≥ 0

items.owner.usernamestring

Owner’s Cosmos username.

items.source_urlstringnullable

Original source URL published with the element, or null.

Published original-source author details, or null.

items.source_author.usernamestringnullable

Source author username, or null.

items.source_author.full_namestringnullable

Source author display name, or null.

items.source_author.profile_urlstringnullable

Source author profile URL, or null.

items.source_author.avatar_urlstringnullable

Source author avatar URL, or null.

Ordered media records attached to the element.

up to 40 items

items.media.idstringnullable

Published media ID, or null.

items.media.typestring

Native Cosmos media type.

min 1 chars

items.media.urlstringnullable

Published media URL, or null.

items.media.widthnumbernullable

Published media width in pixels, or null.

≥ 0

items.media.heightnumbernullable

Published media height in pixels, or null.

≥ 0

items.media.ai_generatedbooleannullable

Published AI-generated flag, or null.

items.media.durationnumbernullable

Published media duration in seconds, or null.

≥ 0

items.media.thumbnail_urlstringnullable

Published thumbnail URL, or null.

items.media.video_urlstringnullable

Published video URL, or null.

items.media.playback_urlstringnullable

Published playback URL, or null.

Published product price, or null.

items.price.valuenumber

Published numeric price value.

items.price.currencystring

Published price currency.

items.brandstringnullable

Published product brand, or null.

items.saved_atstringnullableoptional

Published timestamp when this element was saved in the collection, when present.

Published metadata associated with the ordered media records.

up to 40 items

items.mediaMetadata.idstringnullable

Media ID linking the metadata to a media record, or null.

items.mediaMetadata.blurHashstringnullable

Published blur hash for a media placeholder, or null.

items.mediaMetadata.safetyStatusstringnullable

Published media safety label, or null.

Published source attribution metadata.

items.sourceMetadata.isPublicDomainbooleannullable

Published public-domain flag, or null.

result_countintegernullable

Source-reported result count for the current search retrieval window, or null.

≥ 0

HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.

Error codes

HTTP	failure.code	Meaning
200	`partial`	Usable data with media_incomplete, media_limit, restricted_subcollections_omitted, subcollections_incomplete, subcollection_limit or record_limit coverage warnings.
400	`invalid_request`	Missing, duplicate, malformed, unsafe or unsupported request parameters.
401	`unauthorized`	Missing or invalid service API key.
403	`restricted_page`	The requested Cosmos content is not publicly accessible.
404	`not_found`	The requested public profile, element or collection was not found.
429	`upstream_rate_limited`	Cosmos temporarily rate-limited retrieval.
502	`upstream_challenged`	Cosmos challenged retrieval.
502	`upstream_error`	Source retrieval could not complete.
502	`unsupported_page`	The source response was incomplete, mismatched or unsupported.
502	`response_too_large` `payload_too_complex`	Source data exceeded the byte or parsing limits.
502	`unsafe_redirect` `request_limit`	The source redirect or request sequence exceeded the accepted contract.
503	`busy`	All Cosmos retrieval slots are in use.
504	`timeout`	The total operation deadline expired.

Code example

curl "https://api.scrapeatlas.com/v1/cosmos/search?query=design+references&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.scrapeatlas.com/v1/cosmos/search?query=design+references&limit=20",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data.status, data);

type Result = {
  status: "success" | "partial" | "failed" | "challenged";
  requestId: string;
  [field: string]: unknown;
};

const response = await fetch(
  "https://api.scrapeatlas.com/v1/cosmos/search?query=design+references&limit=20",
  {
    headers: {
      "x-api-key": process.env.SCRAPEATLAS_API_KEY!
    }
  }
);

const data = (await response.json()) as Result;
if (data.status === "failed" || data.status === "challenged") {
  throw new Error(`Cosmos request failed: ${data.requestId}`);
}
console.log(data);

import requests

response = requests.get(
    "https://api.scrapeatlas.com/v1/cosmos/search",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "query": "design references",
        "limit": "20"
    },
    timeout=60,
)
data = response.json()
print(data["status"], data)

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.scrapeatlas.com/v1/cosmos/search?query=design+references&limit=20", nil)
	req.Header.Set("x-api-key", "YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data["status"], data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.scrapeatlas.com/v1/cosmos/search?query=design+references&limit=20"))
            .GET()
            .header("x-api-key", "YOUR_API_KEY")
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Use your sa_live_… customer key at https://api.scrapeatlas.com.

Responses

Successful result. Synthetic example validated against the runtime contract.

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://www.cosmos.so/search/elements/design%20references",
  "fetchedAt": "2026-10-06T00:00:00.000Z",
  "coverage": {
    "source": "public_api",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 2500,
    "durationMs": 300
  },
  "items": [
    {
      "id": 1234567,
      "url": "https://www.cosmos.so/e/1234567",
      "created_at": "2026-10-01T12:00:00.000Z",
      "caption": "Synthetic architectural reference.",
      "text": null,
      "title": null,
      "description": null,
      "owner": {
        "id": 101,
        "username": "example"
      },
      "source_url": "https://example.test/reference",
      "source_author": {
        "username": "example_artist",
        "full_name": "Example Artist",
        "profile_url": "https://example.test/artist",
        "avatar_url": null
      },
      "media": [
        {
          "id": "synthetic-media",
          "type": "StaticImage",
          "url": "https://example.test/reference.jpg",
          "width": 1200,
          "height": 1600,
          "ai_generated": false,
          "duration": null,
          "thumbnail_url": null,
          "video_url": null,
          "playback_url": null
        }
      ],
      "price": null,
      "brand": null,
      "mediaMetadata": [
        {
          "id": "synthetic-media",
          "blurHash": "synthetic-blur-hash",
          "safetyStatus": "safe"
        }
      ],
      "sourceMetadata": {
        "isPublicDomain": false
      }
    }
  ],
  "result_count": 5,
  "cursor": "synthetic-next-cursor",
  "has_more": true
}

Missing, duplicate, malformed, unsafe or unsupported request parameters.

{
  "requestId": "9d2f1c0a-6b1e-4c7d-9a8e-2f3b4c5d6e7f",
  "accounting": {
    "upstreamRequests": 0,
    "responseBytes": 0,
    "durationMs": 0
  },
  "success": false,
  "status": "failed",
  "failure": {
    "code": "invalid_request",
    "message": "Invalid request: missing, duplicate, unsupported or malformed parameters."
  }
}