Read AeoOpportunity
/sites/{site_id}/aeo/opportunities/{record_id}aeo:readRead AeoOpportunity. Only explicitly granted sites and permissions are accessible. No credentials or raw worker payloads are returned. Returns the same public fields as the corresponding list row. Missing, wrong-parent and inaccessible records return the same 404.
| Request | GET https://satelliteai.io/api/v1/sites/{site_id}/aeo/opportunities/{record_id} |
| Permission | aeo:read |
| Response | A single object: data is AeoOpportunity. |
| Operation ID | getAeoOpportunity |
More context and worked examples are in the developer guide.
Example request
curl --fail-with-body \
'https://satelliteai.io/api/v1/sites/123/aeo/opportunities/123' \
-H "Authorization: Bearer $SATELLITE_API_KEY"Replace the example IDs with values returned by the discovery endpoints. Example values are placeholders, not real records.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
site_idrequired | path | integer | Authorized site id. Parent and site grants must also match. min 1 · max 9223372036854775807 |
record_idrequired | path | integer | Authorized record id. Parent and site grants must also match. min 1 · max 9223372036854775807 |
Unknown or repeated query parameters return 400.
Data dictionary
Scoped result. Lists return pagination metadata; unavailable records return 404. Explicit stored AEO fields. Unknown measurements remain null. Scalar lengths are bounded; JSON input is bounded to 262144 characters and nested arrays to 100 items. Check truncated_fields before treating nested content as complete.
[] marks an array element. nullable means the value can be null; treat it as unknown, not zero. always present means the key is always included in the object.
| Field | Type | Description |
|---|---|---|
data.id | integeralways present | Satellite identifier for this record. min 1 |
data.site_id | integernullablealways present | Satellite site ID (from GET /sites). |
data.query | stringnullablealways present | max length 4096 |
data.query_intent | stringnullablealways present | max length 4096 |
data.query_category | stringnullablealways present | max length 4096 |
data.search_volume | integernullablealways present | |
data.monthly_searches | integernullablealways present | |
data.opportunity_type | stringnullablealways present | max length 4096 |
data.opportunity_score | numbernullablealways present | |
data.difficulty_score | numbernullablealways present | |
data.priority_score | numbernullablealways present | |
data.relevance_score | numbernullablealways present | |
data.primary_competitor | stringnullablealways present | max length 4096 |
data.competitor_advantage | stringnullablealways present | max length 4096 |
data.best_matching_url | stringnullablealways present | max length 4096 |
data.our_matching_url | stringnullablealways present | max length 4096 |
data.content_match_url | stringnullablealways present | max length 4096 |
data.content_match_score | numbernullablealways present | |
data.recommended_action | stringnullablealways present | max length 4096 |
data.suggested_content_type | stringnullablealways present | max length 4096 |
data.suggested_angle | stringnullablealways present | max length 4096 |
data.estimated_traffic_if_cited | integernullablealways present | |
data.priority | stringnullablealways present | max length 4096 |
data.status | stringnullablealways present | max length 4096 |
data.discovered_at | string (date-time)nullablealways present | |
data.actioned_at | string (date-time)nullablealways present | |
data.created_at | string (date-time)nullablealways present | When Satellite created the record (UTC, RFC 3339). |
data.updated_at | string (date-time)nullablealways present | When Satellite last updated the record (UTC, RFC 3339). |
data.truncated_fields | array of stringalways present | Public fields whose stored content exceeded scalar, JSON, or nested-array bounds. Empty means no detected truncation. |
data.evidence_type | stringalways present | one of: opportunity |
data.gap_reasons | array of stringnullablealways present | max items 100 |
data.missing_elements | array of stringnullablealways present | max items 100 |
Response metadata
| Field | Type | Description |
|---|---|---|
meta.request_id | stringalways present | Request identifier; also returned in X-Request-ID. Include it in support requests. |
meta.api_version | stringalways present | API version that produced the response. one of: v1 |
meta.limit | integer | Maximum records per page applied to this request. min 1 · max 100 |
meta.has_more | boolean | True when another page is available. |
meta.next_cursor | stringnullable | Opaque cursor for the next page; send as cursor. Null on the last page. |
meta.availability | string | available when stored data exists; not_available when it does not. one of: available, not_available |
meta.billing | object | Present for paid live SERP requests; replayed receipts describe the original debit, not an additional charge. |
meta.billing.operation | stringalways present | one of: client_api_serp_refresh |
meta.billing.credits_charged | integeralways present | min 0 |
meta.billing.transaction_id | integeralways present | |
meta.billing.replayed | booleanalways present |
Error responses
Errors return {"error": {"code", "message", "request_id"}}. See error handling for retry guidance.
| HTTP | When |
|---|---|
400 | Invalid parameters |
401 | Invalid credentials |
403 | Missing permission |
404 | Missing or inaccessible resource |