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

Get research results

Returns the finished, normalized ad records with their source and provenance. Raw provider data and billing details are never included.

GET/v1/research/jobs/{id}/result
Path parameters
idstring<uuid>required
Responses
200Closed normalized Facebook company ads result
dataobjectrequired
Show properties
schema_versionstringrequired
Allowed:research-result@1
kindstringrequired
Allowed:research_result
job_idstring<uuid>required
capability_idstringrequired
Allowed:research.facebook-company-ads@1
statusstringrequired
Allowed:succeeded
cache_dispositionstringrequired
Allowed:cache_hitcache_joinlive_fetchcache_stale
reserved_creditsintegerrequired
min 0 · max 1000000000
maximum_creditsintegerrequired
min 0 · max 1000000000
settled_creditsintegerrequired
min 0 · max 1000000000
provenanceobjectrequired
Show properties
sourcestringrequired
Allowed:facebook
native_idstringrequired
matches ^[1-9][0-9]{4,30}$
fetched_atstring<date-time>required
fresh_throughstring<date-time>required
resultobjectrequired
Show properties
kindstringrequired
Allowed:facebook_company_ads
itemsobject[]required
max items 30
Show properties
Array of object
idstringrequired
matches ^[1-9][0-9]{4,30}$
sourcestringrequired
Allowed:facebook_ad
advertiserobjectrequired
Show properties
idstringrequired
matches ^[1-9][0-9]{4,30}$
namestringrequired
min length 1 · max length 255 · matches \S
avatar_urlstring<uri> | nullrequired
max length 8192
mediaobjectrequired
Show properties
typestringrequired
Allowed:imagevideocarousel
slidesobject[]required
min items 1 · max items 20
Show properties
Array of object
typestringrequired
Allowed:imagevideo
thumbnail_urlstring<uri>required
max length 8192
video_urlstring<uri> | nullrequired
max length 8192
copystring | nullrequired
min length 1 · max length 100000
titlestring | nullrequired
min length 1 · max length 10000
descriptionstring | nullrequired
min length 1 · max length 100000
domainstring | nullrequired
min length 1 · max length 253
ctastring | nullrequired
min length 1 · max length 1000
destination_urlstring<uri> | nullrequired
max length 8192
run_start_datestringrequired
matches ^\d{4}-\d{2}-\d{2}$
run_end_datestring | nullrequired
matches ^\d{4}-\d{2}-\d{2}$
is_activebooleanrequired
platform_linkstring<uri>required
max length 8192
item_countintegerrequired
min 0 · max 30
404Job absent or outside the exact API-key workspace boundary
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
409Job is not yet safely terminal
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
503Research authority or normalized projection 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/research/jobs/%3Cuuid%3E/result"
Response
{
  "data": {
    "schema_version": "research-result@1",
    "kind": "research_result",
    "job_id": "<uuid>",
    "capability_id": "research.facebook-company-ads@1",
    "status": "succeeded",
    "cache_disposition": "cache_hit",
    "reserved_credits": 0,
    "maximum_credits": 0,
    "settled_credits": 0,
    "provenance": {
      "source": "facebook",
      "native_id": "string",
      "fetched_at": "2024-01-01T00:00:00Z",
      "fresh_through": "2024-01-01T00:00:00Z"
    },
    "result": {
      "kind": "facebook_company_ads",
      "items": [
        {
          "id": "string",
          "source": "facebook_ad",
          "advertiser": {
            "id": "string",
            "name": "string",
            "avatar_url": "<uri>"
          },
          "media": {
            "type": "image",
            "slides": [
              {
                "type": "image",
                "thumbnail_url": "<uri>",
                "video_url": "<uri>"
              }
            ]
          },
          "copy": "string",
          "title": "string",
          "description": "string",
          "domain": "string",
          "cta": "string",
          "destination_url": "<uri>",
          "run_start_date": "string",
          "run_end_date": "string",
          "is_active": true,
          "platform_link": "<uri>"
        }
      ],
      "item_count": 0
    }
  }
}