Quote or submit a Research job

Quote or run a Research job. Set quote_only: true to see the price without being charged, then send the same request with its quote_id to run it (costs at most 1 credit). Today this covers Facebook company ads by Page ID: one page, up to 30 results.

POST/v1/research/jobs

Header parameters

Idempotency-Keystringrequired

A unique string that makes retries safe. Any value 16-255 characters; reuse it only when retrying the exact same request.

min length 16 · max length 255 · matches ^[A-Za-z0-9._:-]+$

X-RoasOS-Projectstring

Optional label to group this request under one of your projects. Appears in your usage records.

min length 1 · max length 64 · matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$

X-RoasOS-Cost-Centerstring

Optional label to attribute this request to a cost center. Appears in your usage records.

min length 1 · max length 64 · matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$

Request body

requiredapplication/json

capability_idstringrequired

Allowed:research.facebook-company-ads@1

targetobjectrequired

Show properties

kindstringrequired

Allowed:page_id

page_idstringrequired

matches ^[1-9][0-9]{4,30}$

filtersobjectrequired

Show properties

countrystring

matches ^(?:ALL|[A-Z]{2})$

statusstring

Allowed:ACTIVE

media_typestring

Allowed:ALL

languagestring

matches ^[A-Z]{2}$

sort_bystring

Allowed:relevancy_monthly_grouped

start_datestring

matches ^\d{4}-\d{2}-\d{2}$

end_datestring

matches ^\d{4}-\d{2}-\d{2}$

pageobjectrequired

Show properties

max_pagesnumberrequired

Allowed:1

max_resultsintegerrequired

min 1 · max 30

freshnessobjectrequired

Show properties

max_age_secondsintegerrequired

min 0 · max 21600

allow_stalebooleanrequired

quote_onlyboolean

default: false

quote_idstring<uuid>

Responses

200Immutable quote or free cache-hit job

Any of:

object

dataobjectrequired

Show properties

schema_versionstringrequired

Allowed:research-quote@1

kindstringrequired

Allowed:research_quote

statusstringrequired

Allowed:quoted

quote_idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

cache_dispositionstringrequired

Allowed:cache_hitcache_joinlive_fetchcache_stale

reserved_creditsintegerrequired

min 0 · max 1000000000

maximum_creditsintegerrequired

min 0 · max 1000000000

expires_atstring<date-time>required

pricing_versionstringrequired

min length 1 · max length 80

authorizationobjectrequired

Show properties

Any of:

object

statusstringrequired

Allowed:auto_approved

object

statusstringrequired

Allowed:approval_required

authorize_urlstring<uri>required

max length 2048

confirmationobjectrequired

Show properties

max_pagesintegerrequired

min 1 · max 3

max_resultsintegerrequired

min 1 · max 100

max_age_secondsintegerrequired

min 0 · max 2592000

allow_stalebooleanrequired

object

dataobjectrequired

Show properties

Any of:

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:quoted

cache_dispositionstringrequired

Allowed:live_fetch

reserved_creditsnumberrequired

Allowed:0

quote_idstring<uuid>required

expires_atstring<date-time>required

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:waiting_cache

cache_dispositionstringrequired

Allowed:cache_join

reserved_creditsnumberrequired

Allowed:0

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:queued

cache_dispositionstringrequired

Allowed:live_fetch

reserved_creditsintegerrequired

min 0 · max 1000000000

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:processing

cache_dispositionstringrequired

Allowed:live_fetch

reserved_creditsintegerrequired

min 0 · max 1000000000

started_atstring<date-time>required

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:succeeded

cache_dispositionstringrequired

Allowed:cache_hitcache_joinlive_fetchcache_stale

reserved_creditsintegerrequired

min 0 · max 1000000000

settled_creditsintegerrequired

min 0 · max 1000000000

completed_atstring<date-time>required

result_readybooleanrequired

Allowed:true

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:failed

cache_dispositionstringrequired

Allowed:cache_joinlive_fetch

reserved_creditsintegerrequired

min 0 · max 1000000000

settled_creditsnumberrequired

Allowed:0

completed_atstring<date-time>required

errorobjectrequired

Show properties

codestringrequired

Allowed:research_failednormalization_failed

messagestringrequired

Allowed:Research request failedResearch result could not be normalized

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:unknown

cache_dispositionstringrequired

Allowed:cache_joinlive_fetch

reserved_creditsintegerrequired

min 0 · max 1000000000

reconciliation_requiredbooleanrequired

Allowed:true

202Durably queued live acquisition or free cache join

dataobjectrequired

Show properties

Any of:

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:quoted

cache_dispositionstringrequired

Allowed:live_fetch

reserved_creditsnumberrequired

Allowed:0

quote_idstring<uuid>required

expires_atstring<date-time>required

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:waiting_cache

cache_dispositionstringrequired

Allowed:cache_join

reserved_creditsnumberrequired

Allowed:0

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:queued

cache_dispositionstringrequired

Allowed:live_fetch

reserved_creditsintegerrequired

min 0 · max 1000000000

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:processing

cache_dispositionstringrequired

Allowed:live_fetch

reserved_creditsintegerrequired

min 0 · max 1000000000

started_atstring<date-time>required

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:succeeded

cache_dispositionstringrequired

Allowed:cache_hitcache_joinlive_fetchcache_stale

reserved_creditsintegerrequired

min 0 · max 1000000000

settled_creditsintegerrequired

min 0 · max 1000000000

completed_atstring<date-time>required

result_readybooleanrequired

Allowed:true

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:failed

cache_dispositionstringrequired

Allowed:cache_joinlive_fetch

reserved_creditsintegerrequired

min 0 · max 1000000000

settled_creditsnumberrequired

Allowed:0

completed_atstring<date-time>required

errorobjectrequired

Show properties

codestringrequired

Allowed:research_failednormalization_failed

messagestringrequired

Allowed:Research request failedResearch result could not be normalized

object

schema_versionstringrequired

Allowed:research-job@1

kindstringrequired

Allowed:research_job

idstring<uuid>required

capability_idstringrequired

Allowed:research.facebook-company-ads@1

maximum_creditsintegerrequired

min 0 · max 1000000000

created_atstring<date-time>required

updated_atstring<date-time>required

statusstringrequired

Allowed:unknown

cache_dispositionstringrequired

Allowed:cache_joinlive_fetch

reserved_creditsintegerrequired

min 0 · max 1000000000

reconciliation_requiredbooleanrequired

Allowed:true

400Invalid request, idempotency key, or attribution

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

402Insufficient credits

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

403Explicit spend approval is required

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

409Quote conflict, expiry, or non-terminal retry

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

503Quote, billing, projection, or queue authority 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 POST "https://api.roasos.com/v1/research/jobs" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "capability_id": "research.facebook-company-ads@1",
  "target": {
    "kind": "page_id",
    "page_id": "string"
  },
  "filters": {
    "country": "string",
    "status": "ACTIVE",
    "media_type": "ALL",
    "language": "string",
    "sort_by": "relevancy_monthly_grouped",
    "start_date": "string",
    "end_date": "string"
  },
  "page": {
    "max_pages": 1,
    "max_results": 0
  },
  "freshness": {
    "max_age_seconds": 0,
    "allow_stale": true
  },
  "quote_only": false,
  "quote_id": "<uuid>"
}'

const response = await fetch("https://api.roasos.com/v1/research/jobs", {
  method: "POST",
  headers: {
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "capability_id": "research.facebook-company-ads@1",
  "target": {
    "kind": "page_id",
    "page_id": "string"
  },
  "filters": {
    "country": "string",
    "status": "ACTIVE",
    "media_type": "ALL",
    "language": "string",
    "sort_by": "relevancy_monthly_grouped",
    "start_date": "string",
    "end_date": "string"
  },
  "page": {
    "max_pages": 1,
    "max_results": 0
  },
  "freshness": {
    "max_age_seconds": 0,
    "allow_stale": true
  },
  "quote_only": false,
  "quote_id": "<uuid>"
})
});

import requests

response = requests.post(
    "https://api.roasos.com/v1/research/jobs",
    headers={
        "Idempotency-Key": "string",
        "Content-Type": "application/json"
    },
    json={
  "capability_id": "research.facebook-company-ads@1",
  "target": {
    "kind": "page_id",
    "page_id": "string"
  },
  "filters": {
    "country": "string",
    "status": "ACTIVE",
    "media_type": "ALL",
    "language": "string",
    "sort_by": "relevancy_monthly_grouped",
    "start_date": "string",
    "end_date": "string"
  },
  "page": {
    "max_pages": 1,
    "max_results": 0
  },
  "freshness": {
    "max_age_seconds": 0,
    "allow_stale": True
  },
  "quote_only": False,
  "quote_id": "<uuid>"
},
)

Response

{
  "data": {
    "schema_version": "research-quote@1",
    "kind": "research_quote",
    "status": "quoted",
    "quote_id": "<uuid>",
    "capability_id": "research.facebook-company-ads@1",
    "cache_disposition": "cache_hit",
    "reserved_credits": 0,
    "maximum_credits": 0,
    "expires_at": "2024-01-01T00:00:00Z",
    "pricing_version": "string",
    "authorization": {
      "status": "auto_approved"
    },
    "confirmation": {
      "max_pages": 0,
      "max_results": 0,
      "max_age_seconds": 0,
      "allow_stale": true
    }
  }
}

{
  "data": {
    "schema_version": "research-job@1",
    "kind": "research_job",
    "id": "<uuid>",
    "capability_id": "research.facebook-company-ads@1",
    "maximum_credits": 0,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "status": "quoted",
    "cache_disposition": "live_fetch",
    "reserved_credits": 0,
    "quote_id": "<uuid>",
    "expires_at": "2024-01-01T00:00:00Z"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "request_id": "<uuid>",
    "balance": 0,
    "required": 0,
    "field": "string",
    "state": "string",
    "retryWithNewKey": true,
    "parameter": "string",
    "allowed": [
      "string"
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "request_id": "<uuid>",
    "balance": 0,
    "required": 0,
    "field": "string",
    "state": "string",
    "retryWithNewKey": true,
    "parameter": "string",
    "allowed": [
      "string"
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "request_id": "<uuid>",
    "balance": 0,
    "required": 0,
    "field": "string",
    "state": "string",
    "retryWithNewKey": true,
    "parameter": "string",
    "allowed": [
      "string"
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "request_id": "<uuid>",
    "balance": 0,
    "required": 0,
    "field": "string",
    "state": "string",
    "retryWithNewKey": true,
    "parameter": "string",
    "allowed": [
      "string"
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "request_id": "<uuid>",
    "balance": 0,
    "required": 0,
    "field": "string",
    "state": "string",
    "retryWithNewKey": true,
    "parameter": "string",
    "allowed": [
      "string"
    ]
  }
}