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

Get one ad

Get one cached ad creative by its ID.

GET/v1/discover/items/{id}
Path parameters
idstring<uuid>required
Responses
200Normalized cached creative
dataobjectrequired
Show properties
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}$
400Invalid Discover item ID
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
404Item absent or outside the workspace-visible corpus
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/%3Cuuid%3E"
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"
  }
}