Skip to content
roasOS API
Esc
↑↓navigate↵open⌘Jpreview

Search the ad library

Search ad creatives we have already indexed. Fast, cached, and read-only.

GET/v1/discover/items
Query parameters
viewstring
default: "feed"
Allowed:feedfollowingsaved
sourcesstring[]
max items 3
brand_idsstring<uuid>[]
max items 100
media_typesstring[]
max items 3
sincestring<date-time>
querystring
max length 500
sortstring
default: "newest"
Allowed:newestoldest
cursorstring
Opaque composite pagination cursor from the previous response. Do not parse or construct it.
limitinteger
Number of items to return
min 1 · max 100 · default: 20
Responses
200One bounded page of normalized cached creatives
dataobject[]required
max items 100
Show properties
Array of object
idstring<uuid>required
sourcestringrequired
Allowed:meta_adinstagram_posttiktok_post
brandobjectrequired
Show properties
idstring<uuid>required
slugstringrequired
min length 1 · max length 255
namestringrequired
min length 1 · max length 255
handlestring | nullrequired
min length 1 · max length 255
avatar_urlstring<uri> | nullrequired
max length 4096
mediaobjectrequired
Show properties
aspect_rationumber | nullrequired
min 0 · max 10
slidesobject[]required
max items 20
Show properties
Array of object
typestringrequired
Allowed:imagevideo
thumbnail_urlstring<uri>required
max length 4096
video_urlstring<uri> | nullrequired
max length 4096
copystring | nullrequired
max length 100000
titlestring | nullrequired
max length 10000
descriptionstring | nullrequired
max length 100000
domainstring | nullrequired
max length 253
ctastring | nullrequired
max length 1000
run_start_datestring | nullrequired
matches ^\d{4}-\d{2}-\d{2}$
run_end_datestring | nullrequired
matches ^\d{4}-\d{2}-\d{2}$
is_active_adboolean | nullrequired
post_datestring<date-time> | nullrequired
engagementobject | nullrequired
Show properties
likesintegerrequired
min 0
commentsintegerrequired
min 0
viewsintegerrequired
min 0
platform_linkstring<uri>required
max length 4096
content_atstring<date-time>required
media_typestring | nullrequired
Allowed:imagevideocarousel
verticalstring | nullrequired
max length 255
creative_typestring | nullrequired
max length 255
tagsstring[]required
max items 50
ai_summarystring | nullrequired
max length 20000
languagestring | nullrequired
matches ^[a-z]{2}$
metaobjectrequired
Show properties
cursorstring
min length 1 · max length 4096
has_morebooleanrequired
400Invalid or unsupported filter or cursor
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
403API key no longer has exact Discover read authority
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
503Discover read authority or normalized projection is unavailable
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
Request
curl -X GET "https://api.roasos.com/v1/discover/items"
Response
{
  "data": [
    {
      "id": "<uuid>",
      "source": "meta_ad",
      "brand": {
        "id": "<uuid>",
        "slug": "string",
        "name": "string",
        "handle": "string",
        "avatar_url": "<uri>"
      },
      "media": {
        "aspect_ratio": 0,
        "slides": [
          {
            "type": "image",
            "thumbnail_url": "<uri>",
            "video_url": "<uri>"
          }
        ]
      },
      "copy": "string",
      "title": "string",
      "description": "string",
      "domain": "string",
      "cta": "string",
      "run_start_date": "string",
      "run_end_date": "string",
      "is_active_ad": true,
      "post_date": "2024-01-01T00:00:00Z",
      "engagement": {
        "likes": 0,
        "comments": 0,
        "views": 0
      },
      "platform_link": "<uri>",
      "content_at": "2024-01-01T00:00:00Z",
      "media_type": "image",
      "vertical": "string",
      "creative_type": "string",
      "tags": [
        "string"
      ],
      "ai_summary": "string",
      "language": "string"
    }
  ],
  "meta": {
    "cursor": "string",
    "has_more": true
  }
}