FoxCueDocs
Open FoxCue
API reference

FoxCue API: YouTube performance and Observations

Request examples, parameters, scopes and response statuses for FoxCue API youtube performance and observations.

These operations are copied from the live OpenAPI schema at GET /api/v1/openapi.json (2026-10-28, 297 operations). Each example request is built from that operation's schema: required fields, and optional fields when the object is small. Response bodies are not in that schema. Where the JSON shape is known, it is listed below with an example. Shared errors are on Limits and errors.

Send Authorization: Bearer <workspace API key>. Base URL: https://app.foxcue.com/api/v1.

YouTube performance

GET /performance/capabilities

Discover configured YouTube capabilities, supported reports and setup gaps

Scope: performance:read.

Example request

curl -X GET "https://app.foxcue.com/api/v1/performance/capabilities" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /performance/connections

List OAuth or public API-key channel connections visible to this actor; optional brand project_id

Scope: performance:read.

Parameters

NameInRequiredTypeRules
project_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$

Example request

curl -X GET "https://app.foxcue.com/api/v1/performance/connections?project_id=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /performance/publications

List publications as {items,limit,offset,has_more}; public availability by default

Scope: performance:read.

Parameters

NameInRequiredTypeRules
project_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
connection_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
topic_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
script_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
artifact_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
composition_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
availabilityquerynostringone of all, public, unlisted, private, scheduled, unavailable
linkedquerynostringone of all, linked, unlinked
qquerynostringmaxLength 200
limitquerynointegerminimum 1; maximum 100
offsetquerynointegerminimum 0; maximum 100000

Example request

curl -X GET "https://app.foxcue.com/api/v1/performance/publications?project_id=example&connection_id=example&topic_id=example&script_id=example&artifact_id=example&composition_id=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

The body is a JSON object with these fields.

FieldType
itemsarray
limitnumber
offsetnumber
has_moreboolean
{
  "items": [],
  "limit": 0,
  "offset": 0,
  "has_more": false
}
StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /performance/publications/{id}

Read one visible published video and its explicit content associations

Scope: performance:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/performance/publications/example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

Replace explicit same-brand topic/script/video-artifact links using expected_revision

Scope: performance:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "expected_revision": 1,
  "topic_id": "example",
  "script_id": "example",
  "artifact_id": "example"
}

Required fields: expected_revision.

curl -X PUT "https://app.foxcue.com/api/v1/performance/publications/example/links" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /performance/connections/{id}/sync

Queue YouTube inventory (plus core Analytics for OAuth connections only); body idempotency_key required; at most 367 days

Scope: performance:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "start_date": "example",
  "end_date": "example",
  "idempotency_key": "example-"
}

Required fields: start_date, end_date, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/performance/connections/example/sync" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
202Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /performance/sync-runs/{id}

Poll a visible Performance sync/report run, progress and safe error code

Scope: performance:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/performance/sync-runs/example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /performance/reports

Read cached provider report; missing is not zero; date order and maximum 367-day window required; retention requires publication_id

Scope: performance:read.

Parameters

NameInRequiredTypeRules
connection_idqueryyesstringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
publication_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
familyquerynostringone of totals, daily, traffic, search_terms, retention
start_datequeryyesstringformat date
end_datequeryyesstringformat date

Example request

curl -X GET "https://app.foxcue.com/api/v1/performance/reports?connection_id=example&publication_id=example&family=example&start_date=example&end_date=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

The body is a JSON object with these fields.

FieldType
statusstring
reportnull
{
  "status": "queued",
  "report": null
}
StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /performance/reports/query

Queue one supported Analytics report; body idempotency_key required; poll Performance sync run

Scope: performance:write.

Example request

{
  "query": {
    "connection_id": "example",
    "publication_id": "example",
    "family": "totals",
    "start_date": "example",
    "end_date": "example"
  },
  "idempotency_key": "example-"
}

Required fields: query, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/performance/reports/query" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
202Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

Observations

GET /observations/connections/summary

Aggregate actor-visible integration connection status across brands

Scope: performance:read.

Example request

curl -X GET "https://app.foxcue.com/api/v1/observations/connections/summary" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/page-search

Read authorized stored GSC queries for a page or YouTube video URL; includes weighted position, totals and coverage

Scope: performance:read.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "url": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "search_type": "web",
  "q": "example",
  "limit": 1,
  "offset": 0
}

Required fields: project_id, connection_id, url, window.

curl -X POST "https://app.foxcue.com/api/v1/observations/page-search" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/connections/{id}/sync

Queue an authorized Google resource refresh; durable idempotency, actual adapter and worker status apply

Scope: performance:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "project_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "idempotency_key": "example"
}

Required fields: window, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/observations/connections/example/sync" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
202Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /observations/capabilities

Read actual observation capabilities for a brand

Scope: performance:read.

Parameters

NameInRequiredTypeRules
project_idqueryyesstringminLength 1; maxLength 256

Example request

curl -X GET "https://app.foxcue.com/api/v1/observations/capabilities?project_id=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /observations/connections

List actor-visible brand data resources; setup requires browser owner

Scope: performance:read.

Parameters

NameInRequiredTypeRules
project_idqueryyesstringminLength 1; maxLength 256

Example request

curl -X GET "https://app.foxcue.com/api/v1/observations/connections?project_id=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/uploads

Stage a private CSV up to 10 MiB for an existing authorized resource

Scope: performance:write.

Parameters

NameInRequiredTypeRules
project_idqueryyesstringminLength 1; maxLength 256
connection_idqueryyesstringminLength 1; maxLength 256

Example request

Body is raw bytes (text/csv), not JSON.

curl -X POST "https://app.foxcue.com/api/v1/observations/uploads?project_id=example&connection_id=example" \
  -H "Authorization: Bearer <workspace API key>" \
  --data-binary @file

Response

The body is a JSON object with these fields.

FieldType
idJSON
content_hashJSON
byte_countJSON
expires_atJSON
{
  "id": "id",
  "content_hash": "example",
  "byte_count": "example",
  "expires_at": "2026-10-28T00:00:00.000Z"
}
StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/imports/preview

Validate a staged typed CSV without publishing a batch

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "resource_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "grain": [
    "example"
  ],
  "filters": {},
  "kind": "gsc_page_daily",
  "upload_id": "00000000-0000-4000-8000-000000000000",
  "idempotency_key": "example",
  "schema_version": 1,
  "column_mapping": {}
}

Required fields: project_id, connection_id, resource_id, window, grain, filters, kind, upload_id, idempotency_key, schema_version.

curl -X POST "https://app.foxcue.com/api/v1/observations/imports/preview" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/imports

Publish a typed CSV with an idempotent receipt and row errors

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "resource_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "grain": [
    "example"
  ],
  "filters": {},
  "kind": "gsc_page_daily",
  "upload_id": "00000000-0000-4000-8000-000000000000",
  "idempotency_key": "example",
  "schema_version": 1,
  "column_mapping": {}
}

Required fields: project_id, connection_id, resource_id, window, grain, filters, kind, upload_id, idempotency_key, schema_version.

curl -X POST "https://app.foxcue.com/api/v1/observations/imports" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/page-evidence

Read authorized native-grain page observations with as-of and completeness provenance

Scope: performance:read.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "page_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "as_of": "example",
  "filters": {},
  "limit": 1,
  "offset": 0
}

Required fields: project_id, connection_id, page_id, window.

curl -X POST "https://app.foxcue.com/api/v1/observations/page-evidence" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /observations/runs

List actor-visible resource observation runs

Scope: performance:read.

Parameters

NameInRequiredTypeRules
project_idqueryyesstringminLength 1; maxLength 256
connection_idqueryyesstringminLength 1; maxLength 256

Example request

curl -X GET "https://app.foxcue.com/api/v1/observations/runs?project_id=example&connection_id=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /observations/runs/{id}

Read one authorized observation run

Scope: performance:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/observations/runs/example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /observations/qualification-rules

Read current authored brand qualification rules

Scope: performance:read.

Parameters

NameInRequiredTypeRules
project_idqueryyesstringminLength 1; maxLength 256

Example request

curl -X GET "https://app.foxcue.com/api/v1/observations/qualification-rules?project_id=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

PUT /observations/qualification-rules

Save a versioned explicit qualification rule with revision guard

Scope: performance:write.

Example request

{
  "project_id": "example",
  "id": "example",
  "expected_revision": 0,
  "name": "example",
  "criteria": [
    "example"
  ],
  "active": true
}

Required fields: project_id, expected_revision, name, criteria.

curl -X PUT "https://app.foxcue.com/api/v1/observations/qualification-rules" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

The body is a JSON object with these fields.

FieldType
idJSON
revisionJSON
{
  "id": "id",
  "revision": "example"
}
StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/outcomes

Record one deduplicated outcome stage or retraction; linked pages/videos/intents additionally require strategy:write

Scope: performance:write.

Example request

{
  "input": {
    "project_id": "example",
    "origin": "manual",
    "external_id": "example",
    "occurred_at": "example",
    "kind": "form_submission",
    "attribution": "direct_recorded",
    "qualification_rule_id": "example",
    "qualification_rule_revision": 1,
    "video_id": "example"
  },
  "idempotency_key": "example"
}

Required fields: input, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/observations/outcomes" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

The body is a JSON object with these fields.

FieldType
idJSON
identity_idJSON
revisionJSON
{
  "id": "id",
  "identity_id": "id",
  "revision": "example"
}
StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/outcomes/evidence

Read one latest-asof nonretracted state per outcome identity; no GA4-inferred qualification

Scope: performance:read.

Example request

{
  "project_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "as_of": "example",
  "limit": 1,
  "offset": 0
}

Required fields: project_id, window, as_of.

curl -X POST "https://app.foxcue.com/api/v1/observations/outcomes/evidence" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

The body is a JSON object with these fields.

FieldType
outcomesJSON
next_offsetJSON
qualification_availableJSON
{
  "outcomes": "example",
  "next_offset": "example",
  "qualification_available": "example"
}
StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /observations/outcomes/history

Read retained authored identity revision history

Scope: performance:read.

Parameters

NameInRequiredTypeRules
project_idqueryyesstringminLength 1; maxLength 256
idqueryyesstringminLength 1; maxLength 256
limitquerynointegerminimum 1; maximum 100
offsetquerynointegerminimum 0

Example request

curl -X GET "https://app.foxcue.com/api/v1/observations/outcomes/history?project_id=example&id=example&limit=example&offset=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

The body is a JSON object with these fields.

FieldType
revisionsJSON
next_offsetJSON
{
  "revisions": "example",
  "next_offset": "example"
}
StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/outcomes/imports/preview

Validate typed outcome CSV using existing private observation staging

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "resource_id": "example",
  "upload_id": "00000000-0000-4000-8000-000000000000",
  "idempotency_key": "example"
}

Required fields: project_id, connection_id, resource_id, upload_id, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/observations/outcomes/imports/preview" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/outcomes/imports

Import typed outcome identities with file/request idempotency and row errors

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "resource_id": "example",
  "upload_id": "00000000-0000-4000-8000-000000000000",
  "idempotency_key": "example"
}

Required fields: project_id, connection_id, resource_id, upload_id, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/observations/outcomes/imports" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

PUT /observations/ga4-settings

Configure explicit landing origins and demo event proxy names for an authorized GA4 connection

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "expected_revision": 0,
  "landing_origins": [
    "example"
  ],
  "demo_event_names": [
    "example"
  ]
}

Required fields: project_id, connection_id, expected_revision, landing_origins, demo_event_names.

curl -X PUT "https://app.foxcue.com/api/v1/observations/ga4-settings" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

The body is a JSON object with these fields.

FieldType
revisionJSON
{
  "revision": "example"
}
StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /observations/ga4-settings

Read actor-visible GA4 landing origins/event proxy definitions

Scope: performance:read.

Parameters

NameInRequiredTypeRules
project_idqueryyesstringminLength 1; maxLength 256
connection_idqueryyesstringminLength 1; maxLength 256

Example request

curl -X GET "https://app.foxcue.com/api/v1/observations/ga4-settings?project_id=example&connection_id=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/youtube/reports

Read actor-visible native Performance report families for one linked canonical video; original Pacific definitions and suppressed search terms remain explicit

Scope: performance:read.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "video_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "as_of": "example"
}

Required fields: project_id, connection_id, video_id, window.

curl -X POST "https://app.foxcue.com/api/v1/observations/youtube/reports" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

The body is a JSON object with these fields.

FieldType
video_idJSON
connection_idJSON
timezoneJSON
sourcestring
reportsJSON
attributionstring
qualificationstring
{
  "video_id": "id",
  "connection_id": "id",
  "timezone": "example",
  "source": "example",
  "reports": "example",
  "attribution": "example",
  "qualification": "example"
}
StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/youtube/reports/refresh

Refresh one linked canonical video report through the existing Performance queue; no new OAuth or publishing

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "video_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "family": "totals",
  "idempotency_key": "example-"
}

Required fields: project_id, connection_id, video_id, window, family, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/observations/youtube/reports/refresh" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
202Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /observations/market-capabilities

Read actual keyword configuration and import-only AI visibility capabilities

Scope: performance:read.

Parameters

NameInRequiredTypeRules
project_idqueryyesstringminLength 1; maxLength 256

Example request

curl -X GET "https://app.foxcue.com/api/v1/observations/market-capabilities?project_id=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/keywords/preview

Preview a staged Google Search keyword estimate CSV; close variants and missing values remain explicit

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "resource_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "grain": [
    "example"
  ],
  "filters": {},
  "kind": "keyword_estimates",
  "upload_id": "00000000-0000-4000-8000-000000000000",
  "idempotency_key": "example",
  "schema_version": 1,
  "column_mapping": {}
}

Required fields: project_id, connection_id, resource_id, window, grain, filters, kind, upload_id, idempotency_key, schema_version.

curl -X POST "https://app.foxcue.com/api/v1/observations/keywords/preview" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/keywords/import

Import exact native keyword estimates through the shared idempotent typed observation owner

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "resource_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "grain": [
    "example"
  ],
  "filters": {},
  "kind": "keyword_estimates",
  "upload_id": "00000000-0000-4000-8000-000000000000",
  "idempotency_key": "example",
  "schema_version": 1,
  "column_mapping": {}
}

Required fields: project_id, connection_id, resource_id, window, grain, filters, kind, upload_id, idempotency_key, schema_version.

curl -X POST "https://app.foxcue.com/api/v1/observations/keywords/import" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/keywords/evidence

Read authorized historical keyword estimates without interpreting them as YouTube or prompt volume

Scope: performance:read.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "as_of": "example",
  "filters": {}
}

Required fields: project_id, connection_id, window, as_of.

curl -X POST "https://app.foxcue.com/api/v1/observations/keywords/evidence" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/keywords/estimate

Request historical metrics only through explicit server-configured Google Ads customer authorization; no credentials in arguments

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "idempotency_key": "example-",
  "input": {
    "terms": [
      "example"
    ],
    "country": "example",
    "language": "example",
    "network": "google_search",
    "start_month": "example",
    "end_month": "example"
  }
}

Required fields: project_id, connection_id, idempotency_key, input.

curl -X POST "https://app.foxcue.com/api/v1/observations/keywords/estimate" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

The body is a JSON object with these fields.

FieldType
batch_idJSON
outcomeJSON
{
  "batch_id": "id",
  "outcome": "example"
}
StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/ai-visibility/preview

Preview declared dashboard exports or controlled prompt samples; panel targets additionally require strategy:read

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "resource_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "grain": [
    "example"
  ],
  "filters": {},
  "kind": "google_ai_visibility",
  "upload_id": "00000000-0000-4000-8000-000000000000",
  "idempotency_key": "example",
  "schema_version": 1,
  "samples": [
    {
      "row": 2,
      "target_id": "example",
      "prompt_revision": 1,
      "prompt_version": "example",
      "tested_at": "example",
      "measurement_environment": "consumer_search",
      "citation_urls": [
        "example"
      ],
      "evidence_note": "example"
    }
  ],
  "column_mapping": {},
  "zero_policy": "unknown",
  "format": "canonical"
}

Required fields: project_id, connection_id, resource_id, window, grain, filters, kind, upload_id, idempotency_key, schema_version, samples.

curl -X POST "https://app.foxcue.com/api/v1/observations/ai-visibility/preview" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/ai-visibility/import

Import private AI visibility samples with exact repetitions, provenance and immutable metadata; panel targets additionally require strategy:read

Scope: performance:write.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "resource_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "grain": [
    "example"
  ],
  "filters": {},
  "kind": "google_ai_visibility",
  "upload_id": "00000000-0000-4000-8000-000000000000",
  "idempotency_key": "example",
  "schema_version": 1,
  "samples": [
    {
      "row": 2,
      "target_id": "example",
      "prompt_revision": 1,
      "prompt_version": "example",
      "tested_at": "example",
      "measurement_environment": "consumer_search",
      "citation_urls": [
        "example"
      ],
      "evidence_note": "example"
    }
  ],
  "column_mapping": {},
  "zero_policy": "unknown",
  "format": "canonical"
}

Required fields: project_id, connection_id, resource_id, window, grain, filters, kind, upload_id, idempotency_key, schema_version, samples.

curl -X POST "https://app.foxcue.com/api/v1/observations/ai-visibility/import" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/ai-visibility/evidence

Read scoped private AI samples and their actual tested denominator

Scope: performance:read.

Example request

{
  "project_id": "example",
  "connection_id": "example",
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "as_of": "example",
  "filters": {},
  "target_id": "example"
}

Required fields: project_id, connection_id, window, as_of.

curl -X POST "https://app.foxcue.com/api/v1/observations/ai-visibility/evidence" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /observations/ai-visibility/intents

Read exact AI visibility support for authored canonical intents; additionally requires strategy:read

Scope: performance:read.

Example request

{
  "project_id": "example",
  "intent_ids": [
    "example"
  ],
  "window": {
    "start_date": "example",
    "end_date": "example",
    "timezone": "example"
  },
  "as_of": "example",
  "filters": {}
}

Required fields: project_id, intent_ids, window, as_of.

curl -X POST "https://app.foxcue.com/api/v1/observations/ai-visibility/intents" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

Workflows

Previous Page

Strategy, keywords and citation checks

Next Page

On this page

YouTube performanceGET /performance/capabilitiesExample requestResponseGET /performance/connectionsParametersExample requestResponseGET /performance/publicationsParametersExample requestResponseGET /performance/publications/{id}ParametersExample requestResponsePUT /performance/publications/{id}/linksParametersExample requestResponsePOST /performance/connections/{id}/syncParametersExample requestResponseGET /performance/sync-runs/{id}ParametersExample requestResponseGET /performance/reportsParametersExample requestResponsePOST /performance/reports/queryExample requestResponseObservationsGET /observations/connections/summaryExample requestResponsePOST /observations/page-searchExample requestResponsePOST /observations/connections/{id}/syncParametersExample requestResponseGET /observations/capabilitiesParametersExample requestResponseGET /observations/connectionsParametersExample requestResponsePOST /observations/uploadsParametersExample requestResponsePOST /observations/imports/previewExample requestResponsePOST /observations/importsExample requestResponsePOST /observations/page-evidenceExample requestResponseGET /observations/runsParametersExample requestResponseGET /observations/runs/{id}ParametersExample requestResponseGET /observations/qualification-rulesParametersExample requestResponsePUT /observations/qualification-rulesExample requestResponsePOST /observations/outcomesExample requestResponsePOST /observations/outcomes/evidenceExample requestResponseGET /observations/outcomes/historyParametersExample requestResponsePOST /observations/outcomes/imports/previewExample requestResponsePOST /observations/outcomes/importsExample requestResponsePUT /observations/ga4-settingsExample requestResponseGET /observations/ga4-settingsParametersExample requestResponsePOST /observations/youtube/reportsExample requestResponsePOST /observations/youtube/reports/refreshExample requestResponseGET /observations/market-capabilitiesParametersExample requestResponsePOST /observations/keywords/previewExample requestResponsePOST /observations/keywords/importExample requestResponsePOST /observations/keywords/evidenceExample requestResponsePOST /observations/keywords/estimateExample requestResponsePOST /observations/ai-visibility/previewExample requestResponsePOST /observations/ai-visibility/importExample requestResponsePOST /observations/ai-visibility/evidenceExample requestResponsePOST /observations/ai-visibility/intentsExample requestResponseRelated articles