{ "openapi": "3.0.3", "info": { "title": "Facebook Master Scraper + AI Intelligence", "version": "1.0.0", "description": "66 customer endpoints for bounded public Facebook collection, extraction, filtering, batching, valuation, and deterministic intelligence, plus a dedicated public product health probe. Every POST exposes its complete input in the Params tab as query parameters and has no request body. Successful responses return an exact usage receipt and use bounded disclosed upstream fan-out with no hidden pagination." }, "servers": [ { "url": "https://arbitrage.carvisgsi.xyz", "description": "Provider backend used by RapidAPI Studio." } ], "tags": [ { "name": "Pages", "description": "Public Page details, contact info, media, reviews, ratings, ads, videos, and batch." }, { "name": "Profiles", "description": "Public profile records, posts, photos, reels, and batch." }, { "name": "Posts & Comments", "description": "Posts, comments, replies, reactions, reshares, attachments, and hashtags." }, { "name": "Events", "description": "Public event details and event listings." }, { "name": "Groups", "description": "Public group posts, photos, videos, and events." }, { "name": "Marketplace", "description": "Marketplace listing details and search." }, { "name": "💎 AI Intelligence (Premium)", "description": "💎 Premium endpoints. Deterministic LOW/MEDIUM/HIGH intelligence reports with optional narrated reasoning. Billed as Premium Requests (plus the records they read as Requests)." }, { "name": "Health", "description": "Public, quota-free synthetic product health." } ], "paths": { "/api/facebook/value": { "post": { "operationId": "facebookValue", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Value a Facebook Page", "description": "Return a deterministic Page valuation, confidence, signal breakdown, and optional qualitative explanation. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 1 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: 13 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One handle with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "niche", "in": "query", "required": false, "description": "Optional analysis niche. Defaults to other. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "finance", "tech", "business", "education", "health", "beauty", "fashion", "fitness", "food", "travel", "lifestyle", "entertainment", "gaming", "other" ] }, "example": "education" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 1 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: 13 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One handle with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=13; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 13 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 13 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookValueReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 13 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-value", "handle": "nasa", "niche": "other", "valuation": { "estimateUsd": 36500, "rangeUsd": [ 21900, 51100 ], "confidence": "MEDIUM", "fakeFollowerFlag": false, "signalsUsed": { "followerCount": 275000, "engagementRate": 0.018, "postsLast30d": 18, "accountAgeYears": 6.5, "niche": "other", "hasShopSignal": true } }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 13, "itemsPerUnit": 1, "requestUnits": 13, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 13 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 13 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 13 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 13 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=13; Premium Requests=1", "x-api-aha-results-returned: 13", "x-api-aha-request-units: 13", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One handle with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "niche": "education", "narrate": "false" }, "workedEstimate": "Before calling: 13 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/profile": { "post": { "operationId": "facebookProfile", "tags": [ "Profiles" ], "summary": "Get Page profile signals", "description": "Return normalized public Page profile signals for one handle. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One public handle such as nasa. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Returned normalized Page signals for one handle: follower count, Page age when discoverable, and commerce/shop signals. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One public handle such as nasa. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookProfileReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-profile", "handle": "examplebrand", "followerCount": 275000, "accountAgeYears": 6.5, "hasShopSignal": true, "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One public handle such as nasa.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/posts": { "post": { "operationId": "facebookPosts", "tags": [ "Posts & Comments" ], "summary": "Get recent post aggregates", "description": "Return capped recent-post aggregate signals for one Page handle. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One public handle; no result-limit input. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Returned aggregates from up to 12 recent posts for one handle. `engagementRate` is intentionally null because follower-relative engagement requires profile data; use `/api/facebook/value` for that computed signal. Default result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One public handle; no result-limit input. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookPostsReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-posts", "handle": "examplebrand", "postsSampled": 12, "avgLikesPerPost": 1840, "avgCommentsPerPost": 96, "engagementRate": null, "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 12 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 12, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One public handle; no result-limit input.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/comments": { "post": { "operationId": "facebookComments", "tags": [ "Posts & Comments" ], "summary": "Get comment aggregates", "description": "Return capped public comment aggregate signals for one Page target. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One public handle; no result-limit input. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Returned average likes and replies from up to 50 comments for one Facebook target. Default result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One public handle; no result-limit input. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookCommentsReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-comments", "target": "examplebrand", "commentsSampled": 50, "avgLikesPerComment": 7, "avgRepliesPerComment": 2, "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 12 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 12, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One public handle; no result-limit input.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/groups/feed": { "post": { "operationId": "facebookGroupsFeed", "tags": [ "Groups" ], "summary": "Get posts from a public group", "description": "Collect a capped set of public posts from one Facebook group URL. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook group URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/groups/2204685680" }, { "name": "start_date", "in": "query", "required": false, "description": "Optional lower date boundary. Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2025-01-01" }, { "name": "end_date", "in": "query", "required": false, "description": "Optional upper date boundary. Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2026-07-14" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 10, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 10 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit can only lower the bounded supplier record draw; no continuation is fetched." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/groups/2204685680", "start_date": "2025-01-01", "end_date": "2026-07-14", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/commerce/item": { "post": { "operationId": "facebookCommerceItem", "tags": [ "Marketplace" ], "summary": "Get a Marketplace listing", "description": "Collect one public Marketplace listing by URL. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Marketplace item URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Marketplace item URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/marketplace/item/1378381377569917" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Marketplace item URL. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-commerce", "route": "marketplace", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public Marketplace item URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/marketplace/item/1378381377569917" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Template only: replace the ephemeral URL with a currently verified public target and record the verification timestamp before running." } } }, "/api/facebook/content/item": { "post": { "operationId": "facebookContentItem", "tags": [ "Posts & Comments" ], "summary": "Get a public post", "description": "Collect one public Facebook post by URL. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-post", "route": "post", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public post URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Template only: replace the ephemeral URL with a currently verified public target and record the verification timestamp before running." } } }, "/api/facebook/people/profile": { "post": { "operationId": "facebookPeopleProfile", "tags": [ "Profiles" ], "summary": "Get a public profile", "description": "Collect one public Facebook profile by URL. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One public profile URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook profile URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/zuck" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One public profile URL. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-public-profile", "route": "profile", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One public profile URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/zuck" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/events/detail": { "post": { "operationId": "facebookEventsDetail", "tags": [ "Events" ], "summary": "Get an event", "description": "Collect one public Facebook event by URL. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public event URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook event URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/events/2329826087529589" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public event URL. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-events", "route": "events", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public event URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/events/2329826087529589" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-details": { "post": { "operationId": "facebookPageDetails", "tags": [ "Pages" ], "summary": "Get full public Page details", "description": "Collect one normalized public Page record for buyer-side profile, contact, category, and location workflows. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public Page URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-post-records": { "post": { "operationId": "facebookPagePostRecords", "tags": [ "Pages" ], "summary": "Get bounded Page post records", "description": "Collect up to 12 normalized public post records from one Page URL for buyer-side content workflows. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" }, { "name": "posts_to_not_include", "in": "query", "required": false, "description": "Optional bounded source post identifier exclusion. Send this value as a query Param.", "schema": { "type": "string", "maxLength": 500 }, "example": "1234567890" }, { "name": "start_date", "in": "query", "required": false, "description": "Optional lower date boundary. Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2025-01-01" }, { "name": "end_date", "in": "query", "required": false, "description": "Optional upper date boundary. Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2026-12-31" }, { "name": "include_profile_data", "in": "query", "required": false, "description": "Include available public Page context with collected post records. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 10, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 10 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit can only lower the bounded supplier record draw; no continuation is fetched." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA", "posts_to_not_include": "1234567890", "start_date": "2025-01-01", "end_date": "2026-12-31", "include_profile_data": "false", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/post-comment-records": { "post": { "operationId": "facebookPostCommentRecords", "tags": [ "Posts & Comments" ], "summary": "Get bounded post comment records", "description": "Collect up to 12 normalized public comment records from one post URL for buyer-side moderation and research workflows. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10 and get_all_replies=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, { "name": "get_all_replies", "in": "query", "required": false, "description": "Request available public reply context within the same 12-record hard cap. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false }, { "name": "comments_sort", "in": "query", "required": false, "description": "Supported public comment ordering. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "top", "newest", "all" ] }, "example": "newest" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10 and get_all_replies=false. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 10, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 10 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit can only lower the bounded supplier record draw; no continuation is fetched." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10 and get_all_replies=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l", "get_all_replies": "false", "comments_sort": "newest", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-health-score": { "post": { "operationId": "facebookPageHealthScore", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Score Page health", "description": "Combine profile and recent-post signals into a deterministic Page health score and priorities. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=13; Premium Requests=2" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 13 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 13 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookPageHealthReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Before calling: 13 Requests + 2 Premium Requests maximum.", "value": { "surface": "facebook-page-health-score", "handle": "nasa", "analysis": { "healthScore": 82, "status": "good", "signals": { "followerCount": 26700000, "accountAgeYears": 15.4, "postsSampled": 12, "avgInteractionsPerPost": 18400 }, "priorities": [ "Maintain the current publishing and community-response rhythm." ] }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 13, "itemsPerUnit": 1, "requestUnits": 13, "premiumRequestUnits": 2, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 13 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 13 records read and 2 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=13; Premium Requests=2", "x-api-aha-results-returned: 13", "x-api-aha-request-units: 13", "x-api-aha-premium-request-units: 2", "x-api-aha-upstream-operations: 2", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/growth-forecast": { "post": { "operationId": "facebookGrowthForecast", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Forecast Page growth", "description": "Produce a deterministic baseline follower forecast for a bounded horizon. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "niche", "in": "query", "required": false, "description": "Optional analysis niche. Defaults to other. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "finance", "tech", "business", "education", "health", "beauty", "fashion", "fitness", "food", "travel", "lifestyle", "entertainment", "gaming", "other" ] }, "example": "education" }, { "name": "horizon_days", "in": "query", "required": true, "description": "Forecast horizon in days. Send this value as a query Param.", "schema": { "type": "string", "pattern": "^(30|90|180)$", "description": "Enter 30, 90, or 180. The backend validates this value strictly; no RapidAPI option list is declared because Studio rejects serialized numeric options before forwarding the request." }, "example": "90" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=13; Premium Requests=2" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 13 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 13 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookGrowthForecastReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Before calling: 13 Requests + 2 Premium Requests maximum.", "value": { "surface": "facebook-growth-forecast", "handle": "nasa", "analysis": { "horizonDays": 90, "currentFollowers": 26700000, "projectedFollowers": 27454200, "projectedNetGrowth": 754200, "monthlyGrowthRatePct": 0.93, "forecastConfidence": "MEDIUM", "scenario": "baseline" }, "cached": true, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 13, "itemsPerUnit": 1, "requestUnits": 13, "premiumRequestUnits": 2, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 13 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 13 records read and 2 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=13; Premium Requests=2", "x-api-aha-results-returned: 13", "x-api-aha-request-units: 13", "x-api-aha-premium-request-units: 2", "x-api-aha-upstream-operations: 2", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "niche": "education", "horizon_days": "90", "narrate": "false" }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/engagement-quality": { "post": { "operationId": "facebookEngagementQuality", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Score engagement quality", "description": "Evaluate interaction strength, cadence, and observable audience-risk signals. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "niche", "in": "query", "required": false, "description": "Optional analysis niche. Defaults to other. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "finance", "tech", "business", "education", "health", "beauty", "fashion", "fitness", "food", "travel", "lifestyle", "entertainment", "gaming", "other" ] }, "example": "education" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=13; Premium Requests=2" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 13 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 13 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookEngagementQualityReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Before calling: 13 Requests + 2 Premium Requests maximum.", "value": { "surface": "facebook-engagement-quality", "handle": "nasa", "analysis": { "engagementQualityScore": 76, "grade": "strong", "engagementRatePct": 0.19, "postsLast30d": 24, "consistency": "consistent", "qualitySignals": [ "Audience interaction is healthy for the Page size." ] }, "cached": true, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 13, "itemsPerUnit": 1, "requestUnits": 13, "premiumRequestUnits": 2, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 13 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 13 records read and 2 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=13; Premium Requests=2", "x-api-aha-results-returned: 13", "x-api-aha-request-units: 13", "x-api-aha-premium-request-units: 2", "x-api-aha-upstream-operations: 2", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "niche": "education", "narrate": "false" }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/content-strategy": { "post": { "operationId": "facebookContentStrategy", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Build a content strategy", "description": "Return a deterministic posting cadence, format mix, and next actions for one objective. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "niche", "in": "query", "required": false, "description": "Optional analysis niche. Defaults to other. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "finance", "tech", "business", "education", "health", "beauty", "fashion", "fitness", "food", "travel", "lifestyle", "entertainment", "gaming", "other" ] }, "example": "education" }, { "name": "objective", "in": "query", "required": true, "description": "Primary content objective. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "awareness", "engagement", "conversion" ] }, "example": "engagement" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=13; Premium Requests=2" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 13 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 13 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookContentStrategyReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Before calling: 13 Requests + 2 Premium Requests maximum.", "value": { "surface": "facebook-content-strategy", "handle": "nasa", "analysis": { "objective": "engagement", "currentPostsPerWeek": 5.6, "recommendedPostsPerWeek": 6, "benchmarkInteractionsPerPost": 18400, "formatPlan": [ { "format": "community-prompt", "sharePct": 45 }, { "format": "short-video", "sharePct": 35 }, { "format": "image-story", "sharePct": 20 } ], "nextActions": [ "Publish on a repeatable weekly schedule.", "Turn the strongest audience response into a repeatable series." ] }, "cached": true, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 13, "itemsPerUnit": 1, "requestUnits": 13, "premiumRequestUnits": 2, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 13 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 13 records read and 2 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=13; Premium Requests=2", "x-api-aha-results-returned: 13", "x-api-aha-request-units: 13", "x-api-aha-premium-request-units: 2", "x-api-aha-upstream-operations: 2", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "niche": "education", "objective": "engagement", "narrate": "false" }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/post-virality": { "post": { "operationId": "facebookPostVirality", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Benchmark post virality", "description": "Compare observed post interactions with the Page recent-post baseline. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "observed_likes", "in": "query", "required": true, "description": "Observed like or reaction count. Maximum 2,000,000,000. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 0, "maximum": 2000000000 }, "example": 1800 }, { "name": "observed_comments", "in": "query", "required": true, "description": "Observed comment count. Maximum 2,000,000,000. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 0, "maximum": 2000000000 }, "example": 120 }, { "name": "observed_shares", "in": "query", "required": true, "description": "Observed share count. Maximum 2,000,000,000. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 0, "maximum": 2000000000 }, "example": 240 }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=13; Premium Requests=2" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 13 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 13 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookPostViralityReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Before calling: 13 Requests + 2 Premium Requests maximum.", "value": { "surface": "facebook-post-virality", "handle": "nasa", "analysis": { "observedInteractions": 2160, "baselineInteractionsPerPost": 1200, "breakoutMultiple": 1.8, "viralityScore": 58, "classification": "typical" }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 13, "itemsPerUnit": 1, "requestUnits": 13, "premiumRequestUnits": 2, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 13 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 13 records read and 2 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=13; Premium Requests=2", "x-api-aha-results-returned: 13", "x-api-aha-request-units: 13", "x-api-aha-premium-request-units: 2", "x-api-aha-upstream-operations: 2", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "observed_likes": "1800", "observed_comments": "120", "observed_shares": "240", "narrate": "false" }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/review-sentiment": { "post": { "operationId": "facebookReviewSentiment", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Analyze aggregate review sentiment", "description": "Convert public aggregate rating and review volume into a deterministic sentiment index. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook company reviews URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/PikePlaceChowder/reviews" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookReviewSentimentReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-review-sentiment", "analysis": { "rating": 4.3, "totalReviews": 18420, "sentimentIndex": 86, "sentimentLabel": "positive", "confidence": "HIGH", "reviewVolume": "high", "basis": "aggregate-rating" }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/PikePlaceChowder/reviews", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/reputation-score": { "post": { "operationId": "facebookReputationScore", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Score Page reputation", "description": "Combine audience-quality and aggregate-review signals into a deterministic reputation score. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 25 bounded supplier records. Maximum result size: One report; hard maximum 25 records read and 3 Premium operations. Formula: requestUnits = 25 recordsRead; premiumRequestUnits = 3 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 25 Requests + 3 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "PikePlaceChowder" }, { "name": "niche", "in": "query", "required": false, "description": "Optional analysis niche. Defaults to other. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "finance", "tech", "business", "education", "health", "beauty", "fashion", "fitness", "food", "travel", "lifestyle", "entertainment", "gaming", "other" ] }, "example": "food" }, { "name": "reviews_url", "in": "query", "required": true, "description": "Public Facebook company reviews URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/PikePlaceChowder/reviews" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 25 bounded supplier records. Maximum result size: One report; hard maximum 25 records read and 3 Premium operations. Formula: requestUnits = 25 recordsRead; premiumRequestUnits = 3 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 25 Requests + 3 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=25; Premium Requests=3" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 25 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 25 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 3 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 3 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookReputationReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 25 recordsRead; premiumRequestUnits = 3 boundedOperations. Before calling: 25 Requests + 3 Premium Requests maximum.", "value": { "surface": "facebook-reputation-score", "handle": "PikePlaceChowder", "analysis": { "reputationScore": 78, "status": "good", "audienceTrustScore": 74, "reviewSentimentIndex": 86, "reviewCount": 18420, "riskFlags": [] }, "cached": true, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 25, "itemsPerUnit": 1, "requestUnits": 25, "premiumRequestUnits": 3, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 25 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 25 records read and 3 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 25 recordsRead; premiumRequestUnits = 3 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 25 Requests + 3 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=25; Premium Requests=3", "x-api-aha-results-returned: 25", "x-api-aha-request-units: 25", "x-api-aha-premium-request-units: 3", "x-api-aha-upstream-operations: 3", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "PikePlaceChowder", "niche": "food", "reviews_url": "https://www.facebook.com/PikePlaceChowder/reviews", "narrate": "false" }, "workedEstimate": "Before calling: 25 Requests + 3 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/audience-quality": { "post": { "operationId": "facebookAudienceQuality", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Score audience quality", "description": "Assess observable interaction, activity, and follower-scale anomalies without asserting hidden demographics. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "niche", "in": "query", "required": false, "description": "Optional analysis niche. Defaults to other. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "finance", "tech", "business", "education", "health", "beauty", "fashion", "fitness", "food", "travel", "lifestyle", "entertainment", "gaming", "other" ] }, "example": "education" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 13 bounded supplier records. Maximum result size: One report; hard maximum 13 records read and 2 Premium operations. Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 13 Requests + 2 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=13; Premium Requests=2" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 13 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 13 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 2 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookAudienceQualityReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations. Before calling: 13 Requests + 2 Premium Requests maximum.", "value": { "surface": "facebook-audience-quality", "handle": "nasa", "analysis": { "audienceQualityScore": 79, "authenticityRisk": "low", "followerCount": 26700000, "engagementRatePct": 0.19, "activityLevel": "consistent", "anomalies": [] }, "cached": true, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 13, "itemsPerUnit": 1, "requestUnits": 13, "premiumRequestUnits": 2, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 13 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 13 records read and 2 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 13 recordsRead; premiumRequestUnits = 2 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=13; Premium Requests=2", "x-api-aha-results-returned: 13", "x-api-aha-request-units: 13", "x-api-aha-premium-request-units: 2", "x-api-aha-upstream-operations: 2", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "niche": "education", "narrate": "false" }, "workedEstimate": "Before calling: 13 Requests + 2 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-investment-report": { "post": { "operationId": "facebookPageInvestmentReport", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Build a Page investment report", "description": "Compare asking price with deterministic estimated value and aggregate reputation signals. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 25 bounded supplier records. Maximum result size: One report; hard maximum 25 records read and 3 Premium operations. Formula: requestUnits = 25 recordsRead; premiumRequestUnits = 3 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 25 Requests + 3 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "PikePlaceChowder" }, { "name": "niche", "in": "query", "required": false, "description": "Optional analysis niche. Defaults to other. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "finance", "tech", "business", "education", "health", "beauty", "fashion", "fitness", "food", "travel", "lifestyle", "entertainment", "gaming", "other" ] }, "example": "food" }, { "name": "reviews_url", "in": "query", "required": true, "description": "Public Facebook company reviews URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/PikePlaceChowder/reviews" }, { "name": "asking_price_usd", "in": "query", "required": true, "description": "Positive asking price in US dollars. Maximum 1,000,000,000. Send this value as a query Param.", "schema": { "type": "number", "exclusiveMinimum": true, "maximum": 1000000000, "minimum": 0 }, "example": 12500 }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 25 bounded supplier records. Maximum result size: One report; hard maximum 25 records read and 3 Premium operations. Formula: requestUnits = 25 recordsRead; premiumRequestUnits = 3 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 25 Requests + 3 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=25; Premium Requests=3" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 25 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 25 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 3 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 3 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookPageInvestmentReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 25 recordsRead; premiumRequestUnits = 3 boundedOperations. Before calling: 25 Requests + 3 Premium Requests maximum.", "value": { "surface": "facebook-page-investment-report", "handle": "PikePlaceChowder", "analysis": { "askingPriceUsd": 12500, "estimatedValueUsd": 14700, "estimatedValueRangeUsd": [ 9800, 19600 ], "estimatedUpsidePct": 17.6, "pricePosition": "below-estimate", "investmentScore": 76, "decision": "attractive", "valuationConfidence": "MEDIUM", "reviewSentimentIndex": 86, "dueDiligenceFlags": [] }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 25, "itemsPerUnit": 1, "requestUnits": 25, "premiumRequestUnits": 3, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 25 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 25 records read and 3 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 25 recordsRead; premiumRequestUnits = 3 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 25 Requests + 3 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=25; Premium Requests=3", "x-api-aha-results-returned: 25", "x-api-aha-request-units: 25", "x-api-aha-premium-request-units: 3", "x-api-aha-upstream-operations: 3", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "PikePlaceChowder", "niche": "food", "reviews_url": "https://www.facebook.com/PikePlaceChowder/reviews", "asking_price_usd": "12500", "narrate": "false" }, "workedEstimate": "Before calling: 25 Requests + 3 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/health": { "get": { "operationId": "facebookHealth", "tags": [ "Health" ], "summary": "Check Facebook product health", "description": "Run a public, zero-cost synthetic health check without consuming customer quota.\n\nDefault result size: One synthetic product-health report. Maximum result size: One report. Formula: health_usage_units = 0. Pagination: unsupported. Pagination is not implemented or needed. Worked estimate before running: 1 health call x 0 usage units = 0 usage units. Response usage metadata: No usage header is needed for a zero-unit route. Safe example: GET once; no body or query Params. Non-2xx responses emit no custom usage header.", "x-billing-object": "Health", "responses": { "200": { "description": "The deterministic engine is healthy. Default result size: One synthetic product-health report. Maximum result size: One report. Formula: health_usage_units = 0. Pagination: unsupported. Pagination is not implemented or needed. Worked estimate before running: 1 health call x 0 usage units = 0 usage units. Response usage metadata: No usage header is needed for a zero-unit route. Safe example: GET once; no body or query Params. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookHealthReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: health_usage_units = 0. 1 health call x 0 usage units = 0 usage units.", "value": { "ok": true, "service": "api-aha", "surface": "facebook-intelligence", "status": "ok", "checkedAt": "2026-07-14T14:30:00.000Z" } } } } }, "headers": {} }, "503": { "description": "The deterministic engine reported degraded state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookHealthReport" }, "example": { "ok": false, "service": "api-aha", "surface": "facebook-intelligence", "status": "degraded", "checkedAt": "2026-07-14T14:30:00.000Z" } } } } }, "x-usage-units": { "classification": "Health", "billingObject": "Health", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "health report", "detail": "One synthetic product-health report." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "health report", "detail": "One report." }, "requestedLimit": { "parameter": null, "default": "not applicable", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No limit is accepted and health always uses zero usage units." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "Pagination is not implemented or needed." }, "formula": { "status": "verified", "expression": "health_usage_units = 0", "derivation": "The synthetic health check does not enter a customer usage gate.", "requestedLimitEffect": "No effect.", "repeatedCallEffect": "Every health call remains zero usage units.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "1 health call x 0 usage units = 0 usage units.", "responseUsageMetadata": { "supported": false, "usageUnitHeader": null, "headers": [ "Cache-Control" ], "detail": "No usage header is needed for a zero-unit route." }, "safeLimitExample": "GET once; no body or query Params.", "calibration": { "required": false, "items": [] } }, "x-safe-example": { "queryParams": null, "workedEstimate": "1 health call x 0 usage units = 0 usage units.", "executionGate": "Synthetic product health is safe to run on every schedule." } } }, "/api/facebook/page-contact-info": { "post": { "operationId": "facebookPageContactInfo", "tags": [ "Pages" ], "summary": "Get Page contact info", "description": "Extract public phone, email, website, and address fields from one bounded Page record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public Page URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-about": { "post": { "operationId": "facebookPageAbout", "tags": [ "Pages" ], "summary": "Get Page about section", "description": "Extract the public about, summary, category, and hours fields from one bounded Page record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public Page URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-ratings-summary": { "post": { "operationId": "facebookPageRatingsSummary", "tags": [ "Pages" ], "summary": "Get Page ratings summary", "description": "Extract the public aggregate rating and reviewer-count fields from one bounded Page record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public Page URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-ads": { "post": { "operationId": "facebookPageAds", "tags": [ "Pages" ], "summary": "Get Page Ad Library links", "description": "Extract the public Ad Library links published on one bounded Page record. Links only — no ad-spend, targeting, or Ads Library search data. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public Page URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-identity": { "post": { "operationId": "facebookPageIdentity", "tags": [ "Pages" ], "summary": "Get Page identity record", "description": "Extract the public Page id, delegate Page id, creation time, verification flag, and handle from one bounded Page record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public Page URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public Page URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/reshares": { "post": { "operationId": "facebookReshares", "tags": [ "Posts & Comments" ], "summary": "Get post reshare count", "description": "Extract the public share count from one bounded post record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public post URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/post-reactions": { "post": { "operationId": "facebookPostReactions", "tags": [ "Posts & Comments" ], "summary": "Get post reactions breakdown", "description": "Extract the public reactions-by-type breakdown and deterministic total from one bounded post record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public post URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/post-hashtags": { "post": { "operationId": "facebookPostHashtags", "tags": [ "Posts & Comments" ], "summary": "Get post hashtags", "description": "Extract the public hashtag list from one bounded post record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public post URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/post-link-preview": { "post": { "operationId": "facebookPostLinkPreview", "tags": [ "Posts & Comments" ], "summary": "Get post link preview", "description": "Extract the public external link, title, image, and description from one bounded post record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public post URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/post-sponsored-check": { "post": { "operationId": "facebookPostSponsoredCheck", "tags": [ "Posts & Comments" ], "summary": "Check post sponsorship", "description": "Extract the public sponsored flag and sponsor name from one bounded post record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public post URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/post-attachments": { "post": { "operationId": "facebookPostAttachments", "tags": [ "Posts & Comments" ], "summary": "Get post attachments", "description": "Extract the public attachment list (type, media URLs, thumbnails) from one bounded post record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public post URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public post URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/post-video-details": { "post": { "operationId": "facebookPostVideoDetails", "tags": [ "Posts & Comments" ], "summary": "Get post video details", "description": "Extract the public video view count, video URL, length, and thumbnail from one bounded post record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public video post URL. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One current public video post URL. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookExtractReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-page-contact-info", "route": "pages", "target": "https://www.facebook.com/NASA", "data": { "emails": [ "press@example.com" ], "phones": null, "websites": [ "https://example.com" ], "externalWebsite": "https://example.com", "address": null }, "cached": false, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One current public video post URL.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-videos": { "post": { "operationId": "facebookPageVideos", "tags": [ "Pages" ], "summary": "List Page video posts", "description": "Collect a bounded recent-post sample from one Page URL and return only posts with video attachments. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookFilteredReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-page-videos", "route": "posts", "count": 2, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "text": "Launch replay", "likes": 1800, "comments": 120, "shares": 45, "date": "2026-07-10T18:00:00.000Z", "mediaType": "video" }, { "id": "fb_124", "url": "https://www.facebook.com/example/posts/124", "text": "Behind the scenes", "likes": 900, "comments": 60, "shares": 12, "date": "2026-07-08T18:00:00.000Z", "mediaType": "video" } ], "filteredFrom": 10, "cached": false, "nextCursor": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 2, "recordsRead": 10, "itemsPerUnit": 1, "requestUnits": 10, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=10" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 2 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 10 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 12 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit caps matching items returned, while Requests recover the full bounded sample disclosed by filteredFrom." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "A smaller match limit does not reduce the bounded sample read.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-photos": { "post": { "operationId": "facebookPagePhotos", "tags": [ "Pages" ], "summary": "List Page photo posts", "description": "Collect a bounded recent-post sample from one Page URL and return only posts with photo attachments. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookFilteredReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-page-videos", "route": "posts", "count": 2, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "text": "Launch replay", "likes": 1800, "comments": 120, "shares": 45, "date": "2026-07-10T18:00:00.000Z", "mediaType": "video" }, { "id": "fb_124", "url": "https://www.facebook.com/example/posts/124", "text": "Behind the scenes", "likes": 900, "comments": 60, "shares": 12, "date": "2026-07-08T18:00:00.000Z", "mediaType": "video" } ], "filteredFrom": 10, "cached": false, "nextCursor": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 2, "recordsRead": 10, "itemsPerUnit": 1, "requestUnits": 10, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=10" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 2 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 10 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 12 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit caps matching items returned, while Requests recover the full bounded sample disclosed by filteredFrom." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "A smaller match limit does not reduce the bounded sample read.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/group-posts-photos": { "post": { "operationId": "facebookGroupPostsPhotos", "tags": [ "Groups" ], "summary": "List group photo posts", "description": "Collect a bounded public group-post sample and return only posts with photo attachments. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook group URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/groups/2204685680" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookFilteredReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-page-videos", "route": "posts", "count": 2, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "text": "Launch replay", "likes": 1800, "comments": 120, "shares": 45, "date": "2026-07-10T18:00:00.000Z", "mediaType": "video" }, { "id": "fb_124", "url": "https://www.facebook.com/example/posts/124", "text": "Behind the scenes", "likes": 900, "comments": 60, "shares": 12, "date": "2026-07-08T18:00:00.000Z", "mediaType": "video" } ], "filteredFrom": 10, "cached": false, "nextCursor": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 2, "recordsRead": 10, "itemsPerUnit": 1, "requestUnits": 10, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=10" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 2 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 10 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 12 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit caps matching items returned, while Requests recover the full bounded sample disclosed by filteredFrom." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "A smaller match limit does not reduce the bounded sample read.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/groups/2204685680", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/group-posts-videos": { "post": { "operationId": "facebookGroupPostsVideos", "tags": [ "Groups" ], "summary": "List group video posts", "description": "Collect a bounded public group-post sample and return only posts with video attachments. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook group URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/groups/2204685680" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookFilteredReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-page-videos", "route": "posts", "count": 2, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "text": "Launch replay", "likes": 1800, "comments": 120, "shares": 45, "date": "2026-07-10T18:00:00.000Z", "mediaType": "video" }, { "id": "fb_124", "url": "https://www.facebook.com/example/posts/124", "text": "Behind the scenes", "likes": 900, "comments": 60, "shares": 12, "date": "2026-07-08T18:00:00.000Z", "mediaType": "video" } ], "filteredFrom": 10, "cached": false, "nextCursor": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 2, "recordsRead": 10, "itemsPerUnit": 1, "requestUnits": 10, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=10" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 2 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 10 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 12 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit caps matching items returned, while Requests recover the full bounded sample disclosed by filteredFrom." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "A smaller match limit does not reduce the bounded sample read.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/groups/2204685680", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/profile-photos": { "post": { "operationId": "facebookProfilePhotos", "tags": [ "Profiles" ], "summary": "List profile photo posts", "description": "Collect a bounded recent-post sample from one public profile URL and return only posts with photo attachments. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook profile URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/zuck" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookFilteredReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-page-videos", "route": "posts", "count": 2, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "text": "Launch replay", "likes": 1800, "comments": 120, "shares": 45, "date": "2026-07-10T18:00:00.000Z", "mediaType": "video" }, { "id": "fb_124", "url": "https://www.facebook.com/example/posts/124", "text": "Behind the scenes", "likes": 900, "comments": 60, "shares": 12, "date": "2026-07-08T18:00:00.000Z", "mediaType": "video" } ], "filteredFrom": 10, "cached": false, "nextCursor": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 2, "recordsRead": 10, "itemsPerUnit": 1, "requestUnits": 10, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=10" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 2 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 10 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 12 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit caps matching items returned, while Requests recover the full bounded sample disclosed by filteredFrom." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "A smaller match limit does not reduce the bounded sample read.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/zuck", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/comment-by-id": { "post": { "operationId": "facebookCommentById", "tags": [ "Posts & Comments" ], "summary": "Get one comment by id", "description": "Collect the bounded comment sample for one post URL and return the comment matching the supplied comment id, or a 404 when it is not in the sample. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One post URL plus its comment id. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02axy8aC3J8GxKyBYfkWaj7HgysnudBKD3e4aW61jEYes5zVrKsSUvY5qqsFiQNbQJl" }, { "name": "comment_id", "in": "query", "required": true, "description": "Public comment id to match within the bounded sample. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "example": "Y29tbWVudDoxNTY2NTAxMDQxNTExOTMzXzE1NTM2MjM2NDMwNjIwOTU=" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 12 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One post URL plus its comment id. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookFilteredReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-page-videos", "route": "posts", "count": 2, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "text": "Launch replay", "likes": 1800, "comments": 120, "shares": 45, "date": "2026-07-10T18:00:00.000Z", "mediaType": "video" }, { "id": "fb_124", "url": "https://www.facebook.com/example/posts/124", "text": "Behind the scenes", "likes": 900, "comments": 60, "shares": 12, "date": "2026-07-08T18:00:00.000Z", "mediaType": "video" } ], "filteredFrom": 10, "cached": false, "nextCursor": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 2, "recordsRead": 10, "itemsPerUnit": 1, "requestUnits": 10, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=10" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 2 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 10 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 12 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 12, "effectOnUnits": "limit caps matching items returned, while Requests recover the full bounded sample disclosed by filteredFrom." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "A smaller match limit does not reduce the bounded sample read.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One post URL plus its comment id.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02axy8aC3J8GxKyBYfkWaj7HgysnudBKD3e4aW61jEYes5zVrKsSUvY5qqsFiQNbQJl", "comment_id": "Y29tbWVudDoxNTY2NTAxMDQxNTExOTMzXzE1NTM2MjM2NDMwNjIwOTU=" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-details-by-id": { "post": { "operationId": "facebookPageDetailsById", "tags": [ "Pages" ], "summary": "Get Page details by id", "description": "Collect one normalized public Page record by numeric Page id. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One numeric Page id. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "page_id", "in": "query", "required": true, "description": "Numeric Facebook Page id. Send this value as a query Param.", "schema": { "type": "string", "pattern": "^\\d{3,25}$", "maxLength": 25 }, "example": "104958162837" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One numeric Page id. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One numeric Page id.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "page_id": "104958162837" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/profile-details-by-id": { "post": { "operationId": "facebookProfileDetailsById", "tags": [ "Profiles" ], "summary": "Get profile by id", "description": "Collect one public profile record by numeric profile id. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One numeric profile id. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "profile_id", "in": "query", "required": true, "description": "Numeric Facebook profile id. Send this value as a query Param.", "schema": { "type": "string", "pattern": "^\\d{3,25}$", "maxLength": 25 }, "example": "4" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One numeric profile id. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One numeric profile id.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "profile_id": "4" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/event-details-by-id": { "post": { "operationId": "facebookEventDetailsById", "tags": [ "Events" ], "summary": "Get event by id", "description": "Collect one public event record by numeric event id. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One numeric event id. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "event_id", "in": "query", "required": true, "description": "Numeric Facebook event id. Send this value as a query Param.", "schema": { "type": "string", "pattern": "^\\d{3,25}$", "maxLength": 25 }, "example": "2329826087529589" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 1 records under the default input. Maximum result size: Hard maximum 1 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 1 Requests for 1 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: One numeric event id. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 1 Requests for 1 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "A successful call reads at most 1 records under the default input." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "bounded supplier records read", "detail": "Hard maximum 1 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "One numeric event id.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "event_id": "2329826087529589" }, "workedEstimate": "Before calling: at most 1 Requests for 1 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/profile-posts": { "post": { "operationId": "facebookProfilePosts", "tags": [ "Profiles" ], "summary": "List profile posts", "description": "Collect bounded public post records from one public profile URL. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook profile URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/zuck" }, { "name": "posts_to_not_include", "in": "query", "required": false, "description": "Optional comma-separated post ids to exclude. Send this value as a query Param.", "schema": { "type": "string", "maxLength": 500 }, "example": "" }, { "name": "start_date", "in": "query", "required": false, "description": "Window start date (YYYY-MM-DD). Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2025-01-01" }, { "name": "end_date", "in": "query", "required": false, "description": "Window end date (YYYY-MM-DD). Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2026-12-31" }, { "name": "include_profile_data", "in": "query", "required": false, "description": "Attach public profile-level fields to the records. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 10, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 10 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit can only lower the bounded supplier record draw; no continuation is fetched." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/zuck", "posts_to_not_include": "", "start_date": "2025-01-01", "end_date": "2026-12-31", "include_profile_data": "false", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/group-posts-by-date": { "post": { "operationId": "facebookGroupPostsByDate", "tags": [ "Groups" ], "summary": "List group posts by date window", "description": "Collect bounded public group posts limited to an explicit start/end date window. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10 with an explicit start_date/end_date. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook group URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/groups/DogspottingSociety" }, { "name": "start_date", "in": "query", "required": true, "description": "Window start date (YYYY-MM-DD). Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2026-01-01" }, { "name": "end_date", "in": "query", "required": true, "description": "Window end date (YYYY-MM-DD). Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2026-12-31" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10 with an explicit start_date/end_date. Non-2xx responses emit no custom usage header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookFilteredReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-page-videos", "route": "posts", "count": 2, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "text": "Launch replay", "likes": 1800, "comments": 120, "shares": 45, "date": "2026-07-10T18:00:00.000Z", "mediaType": "video" }, { "id": "fb_124", "url": "https://www.facebook.com/example/posts/124", "text": "Behind the scenes", "likes": 900, "comments": 60, "shares": 12, "date": "2026-07-08T18:00:00.000Z", "mediaType": "video" } ], "filteredFrom": 10, "cached": false, "nextCursor": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 2, "recordsRead": 10, "itemsPerUnit": 1, "requestUnits": 10, "formula": "1 Request per supplier record read" } } } } } }, "headers": { "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=10" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 2 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 10 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 10, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 10 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit caps matching items returned, while Requests recover the full bounded sample disclosed by filteredFrom." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "A smaller match limit does not reduce the bounded sample read.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10 with an explicit start_date/end_date.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/groups/DogspottingSociety", "start_date": "2026-01-01", "end_date": "2026-12-31", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/posts-by-date": { "post": { "operationId": "facebookPostsByDate", "tags": [ "Posts & Comments" ], "summary": "List Page posts by date window", "description": "Collect bounded public Page posts limited to an explicit start/end date window. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10 with an explicit start_date/end_date. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA" }, { "name": "start_date", "in": "query", "required": true, "description": "Window start date (YYYY-MM-DD). Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2025-01-01" }, { "name": "end_date", "in": "query", "required": true, "description": "Window end date (YYYY-MM-DD). Send this value as a query Param.", "schema": { "type": "string", "maxLength": 40 }, "example": "2026-12-31" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10 with an explicit start_date/end_date. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 10, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 10 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit can only lower the bounded supplier record draw; no continuation is fetched." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10 with an explicit start_date/end_date.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA", "start_date": "2025-01-01", "end_date": "2026-12-31", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-reviews": { "post": { "operationId": "facebookPageReviews", "tags": [ "Pages" ], "summary": "List Page review records", "description": "Collect bounded public review records (content, recommendation, reactions, replies) for one Page URL. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Use the Page reviews URL (…/reviews). Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/PikePlaceChowder/reviews" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 10 records under the default input. Maximum result size: Hard maximum 12 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 12 Requests for 12 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: limit=10. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 12 Requests for 12 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 10, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 10 records under the default input." }, "maximumResultSize": { "count": 12, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 12 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 12, "effectOnUnits": "limit can only lower the bounded supplier record draw; no continuation is fetched." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/PikePlaceChowder/reviews", "limit": "10" }, "workedEstimate": "Before calling: at most 12 Requests for 12 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/pages-batch": { "post": { "operationId": "facebookPagesBatch", "tags": [ "Pages" ], "summary": "Batch Page details", "description": "Collect one normalized public Page record per URL in one bounded operation. 20 URLs maximum; 20 URLs × 1 record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 20 records under the default input. Maximum result size: Hard maximum 20 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 20 Requests for 20 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two public Page URLs. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "urls", "in": "query", "required": true, "description": "Up to 20 public Page URLs. As a query parameter, pass a comma-separated list. Send 1-20 values as one comma-separated query string.", "x-query-serialization": "comma-separated", "schema": { "type": "string", "minLength": 1, "description": "Comma-separated list of URLs. The backend accepts 1-20 items." }, "example": "https://www.facebook.com/NASA,https://www.facebook.com/nba" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 20 records under the default input. Maximum result size: Hard maximum 20 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 20 Requests for 20 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two public Page URLs. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 20 Requests for 20 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 20, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 20 records under the default input." }, "maximumResultSize": { "count": 20, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 20 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 20, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 20 Requests for 20 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "Two public Page URLs.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "urls": "https://www.facebook.com/NASA,https://www.facebook.com/nba" }, "workedEstimate": "Before calling: at most 20 Requests for 20 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/profiles-batch": { "post": { "operationId": "facebookProfilesBatch", "tags": [ "Profiles" ], "summary": "Batch profiles", "description": "Collect one public profile record per URL in one bounded operation. 20 URLs maximum; 20 URLs × 1 record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 20 records under the default input. Maximum result size: Hard maximum 20 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 20 Requests for 20 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two public profile URLs. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "urls", "in": "query", "required": true, "description": "Up to 20 public profile URLs. As a query parameter, pass a comma-separated list. Send 1-20 values as one comma-separated query string.", "x-query-serialization": "comma-separated", "schema": { "type": "string", "minLength": 1, "description": "Comma-separated list of URLs. The backend accepts 1-20 items." }, "example": "https://www.facebook.com/zuck" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 20 records under the default input. Maximum result size: Hard maximum 20 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 20 Requests for 20 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two public profile URLs. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 20 Requests for 20 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 20, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 20 records under the default input." }, "maximumResultSize": { "count": 20, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 20 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 20, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 20 Requests for 20 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "Two public profile URLs.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "urls": "https://www.facebook.com/zuck" }, "workedEstimate": "Before calling: at most 20 Requests for 20 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/events-batch": { "post": { "operationId": "facebookEventsBatch", "tags": [ "Events" ], "summary": "Batch events", "description": "Collect one public event record per URL in one bounded operation. 20 URLs maximum; 20 URLs × 1 record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 20 records under the default input. Maximum result size: Hard maximum 20 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 20 Requests for 20 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two public event URLs. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "urls", "in": "query", "required": true, "description": "Up to 20 public event URLs. As a query parameter, pass a comma-separated list. Send 1-20 values as one comma-separated query string.", "x-query-serialization": "comma-separated", "schema": { "type": "string", "minLength": 1, "description": "Comma-separated list of URLs. The backend accepts 1-20 items." }, "example": "https://www.facebook.com/events/24934299632891675,https://www.facebook.com/events/1058297040385012" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 20 records under the default input. Maximum result size: Hard maximum 20 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 20 Requests for 20 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two public event URLs. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 20 Requests for 20 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 20, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 20 records under the default input." }, "maximumResultSize": { "count": 20, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 20 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 20, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 20 Requests for 20 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "Two public event URLs.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "urls": "https://www.facebook.com/events/24934299632891675,https://www.facebook.com/events/1058297040385012" }, "workedEstimate": "Before calling: at most 20 Requests for 20 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/marketplace-batch": { "post": { "operationId": "facebookMarketplaceBatch", "tags": [ "Marketplace" ], "summary": "Batch Marketplace listings", "description": "Collect one public Marketplace listing per URL in one bounded operation. 20 URLs maximum; 20 URLs × 1 record. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 20 records under the default input. Maximum result size: Hard maximum 20 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 20 Requests for 20 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two public Marketplace item URLs. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "urls", "in": "query", "required": true, "description": "Up to 20 public Marketplace item URLs. As a query parameter, pass a comma-separated list. Send 1-20 values as one comma-separated query string.", "x-query-serialization": "comma-separated", "schema": { "type": "string", "minLength": 1, "description": "Comma-separated list of URLs. The backend accepts 1-20 items." }, "example": "https://www.facebook.com/marketplace/item/4619779368245338,https://www.facebook.com/marketplace/item/2060777657867468" } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 20 records under the default input. Maximum result size: Hard maximum 20 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 20 Requests for 20 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two public Marketplace item URLs. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 20 Requests for 20 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 20, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 20 records under the default input." }, "maximumResultSize": { "count": 20, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 20 records read in one call." }, "requestedLimit": { "parameter": null, "default": "no result-limit parameter", "acceptedMaximum": null, "effectiveMaximum": 20, "effectOnUnits": "The route has a fixed bounded record draw and no continuation input." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 20 Requests for 20 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "Two public Marketplace item URLs.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "urls": "https://www.facebook.com/marketplace/item/4619779368245338,https://www.facebook.com/marketplace/item/2060777657867468" }, "workedEstimate": "Before calling: at most 20 Requests for 20 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/posts-batch": { "post": { "operationId": "facebookPostsBatch", "tags": [ "Posts & Comments" ], "summary": "Batch Page posts", "description": "Collect bounded public posts for up to 5 Page URLs in one bounded operation. 5 URLs × up to 12 posts = 60 records maximum. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 50 records under the default input. Maximum result size: Hard maximum 60 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 60 Requests for 60 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two Page URLs with limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "urls", "in": "query", "required": true, "description": "Up to 5 public Page URLs. As a query parameter, pass a comma-separated list. Send 1-5 values as one comma-separated query string.", "x-query-serialization": "comma-separated", "schema": { "type": "string", "minLength": 1, "description": "Comma-separated list of URLs. The backend accepts 1-5 items." }, "example": "https://www.facebook.com/NASA,https://www.facebook.com/nba" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 50 records under the default input. Maximum result size: Hard maximum 60 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 60 Requests for 60 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two Page URLs with limit=10. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 60 Requests for 60 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 50, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 50 records under the default input." }, "maximumResultSize": { "count": 60, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 60 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 60, "effectOnUnits": "limit can only lower the bounded supplier record draw; no continuation is fetched." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 60 Requests for 60 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "Two Page URLs with limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "urls": "https://www.facebook.com/NASA,https://www.facebook.com/nba", "limit": "10" }, "workedEstimate": "Before calling: at most 60 Requests for 60 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/comments-batch": { "post": { "operationId": "facebookCommentsBatch", "tags": [ "Posts & Comments" ], "summary": "Batch post comments", "description": "Collect bounded public comments for up to 5 post URLs in one bounded operation. 5 URLs × up to 12 comments = 60 records maximum. Send every input through the Params tab as query parameters; this operation has no request body.\n\nDefault result size: A successful call reads at most 50 records under the default input. Maximum result size: Hard maximum 60 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 60 Requests for 60 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two post URLs with limit=10. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "urls", "in": "query", "required": true, "description": "Up to 5 public post URLs. As a query parameter, pass a comma-separated list. Send 1-5 values as one comma-separated query string.", "x-query-serialization": "comma-separated", "schema": { "type": "string", "minLength": 1, "description": "Comma-separated list of URLs. The backend accepts 1-5 items." }, "example": "https://www.facebook.com/NASA/posts/pfbid02axy8aC3J8GxKyBYfkWaj7HgysnudBKD3e4aW61jEYes5zVrKsSUvY5qqsFiQNbQJl,https://www.facebook.com/NASA/posts/pfbid0nLvhmNSdY9gF7YLDnWEBpQmS9fzNPobBz9Y1YTb2xzAYFyoeqrTZzX1NosGBaDLKl" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results returned from one bounded upstream operation. Default 10; hard maximum 12. No next page is fetched. Send this value as a query Param.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 10 } ], "x-billing-object": "Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful response. Default result size: A successful call reads at most 50 records under the default input. Maximum result size: Hard maximum 60 records read in one call. Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call follows the formula again. Worked estimate before running: Before calling: at most 60 Requests for 60 bounded records read. Response usage metadata: Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap. Safe example: Two post URLs with limit=10. Non-2xx responses emit no custom usage header.", "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Request correlation id." }, "x-facebook-plan": { "schema": { "type": "string", "enum": [ "Free", "Pro", "Ultra" ] }, "description": "Resolved plan for this Facebook product." }, "x-facebook-product": { "schema": { "type": "string", "enum": [ "value", "profile", "posts", "comments", "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "public-profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "description": "Metered Facebook product bucket." }, "x-facebook-quota-limit": { "schema": { "type": "integer" }, "description": "Monthly calls included for this product." }, "x-facebook-quota-remaining": { "schema": { "type": "integer" }, "description": "Calls remaining after this request." }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookRawReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = max(1, recordsRead); itemsPerUnit = 1. Before calling: at most 60 Requests for 60 bounded records read.", "value": { "surface": "facebook-groups-feed", "route": "posts-by-group", "count": 1, "items": [ { "id": "fb_123", "url": "https://www.facebook.com/example/posts/123", "title": "Summer pop-up market", "text": "New collection preview is live today.", "author": "Example Brand", "category": "Apparel", "location": "Austin, TX", "date": "2026-07-09", "likes": 1280, "comments": 84, "shares": 22, "views": 18400, "price": 850, "currency": "USD", "followers": 275000, "attendees": 340 } ], "cached": false, "generatedAt": "2026-07-10T12:00:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 1, "itemsPerUnit": 1, "requestUnits": 1, "formula": "1 Request per supplier record read" }, "nextCursor": null } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Standard", "billingObject": "Requests", "defaultResultSize": { "count": 50, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "A successful call reads at most 50 records under the default input." }, "maximumResultSize": { "count": 60, "qualifier": "up to", "unit": "bounded supplier records read", "detail": "Hard maximum 60 records read in one call." }, "requestedLimit": { "parameter": "limit", "default": "10", "acceptedMaximum": 12, "effectiveMaximum": 60, "effectOnUnits": "limit can only lower the bounded supplier record draw; no continuation is fetched." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call follows the formula again." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = max(1, recordsRead); itemsPerUnit = 1", "derivation": "Every bounded supplier record read is recovered as one Request.", "requestedLimitEffect": "Where accepted, limit can only reduce recordsRead.", "repeatedCallEffect": "Every successful buyer call applies the same disclosed formula; no next page is auto-fetched.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: at most 60 Requests for 60 bounded records read.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=", "x-api-aha-results-returned", "x-api-aha-request-units", "x-api-aha-bundle-size: 1", "x-api-aha-unit-formula", "x-request-id" ], "detail": "Success exposes the bounded record draw, exact Request units, one-record bundle, and hard cap." }, "safeLimitExample": "Two post URLs with limit=10.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and RapidAPI gateway receipt before publication." ] } }, "x-safe-example": { "queryParams": { "urls": "https://www.facebook.com/NASA/posts/pfbid02axy8aC3J8GxKyBYfkWaj7HgysnudBKD3e4aW61jEYes5zVrKsSUvY5qqsFiQNbQJl,https://www.facebook.com/NASA/posts/pfbid0nLvhmNSdY9gF7YLDnWEBpQmS9fzNPobBz9Y1YTb2xzAYFyoeqrTZzX1NosGBaDLKl", "limit": "10" }, "workedEstimate": "Before calling: at most 60 Requests for 60 bounded records read.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/brand-safety-score": { "post": { "operationId": "facebookBrandSafetyScore", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Score brand safety signals", "description": "Deterministic brand-safety screening from sponsored share, external-link share, comment anomalies, and activity in a bounded recent-post sample. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookBrandSafetyReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-brand-safety-score", "handle": "nasa", "analysis": { "brandSafetyScore": 90, "band": "low-risk", "basis": "bounded-recent-post-signal-sample", "sampleSize": 12, "sponsoredSharePct": 8.3, "externalLinkSharePct": 25, "commentAnomalyCount": 0, "activityLevel": "consistent", "signals": [ "No elevated content-signal risks were observed in the sample." ], "limitation": "Signal-based screening only - no text/content moderation analysis was performed. Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/crisis-detection": { "post": { "operationId": "facebookCrisisDetection", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Detect engagement crisis signals", "description": "Deterministic anomaly screening of comment-to-reaction ratios and engagement collapse in a bounded recent-post sample. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookCrisisDetectionReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-crisis-detection", "handle": "nasa", "analysis": { "crisisSignal": "none", "basis": "comment-to-reaction-anomalies-in-bounded-sample", "sampleSize": 12, "baselineCommentReactionRatio": 0.06, "anomalousPosts": 0, "engagementCollapseDetected": false, "observations": [ "No anomaly pattern was observed in the bounded sample." ], "limitation": "Anomaly screening from public engagement counts only; comment text and sentiment are not analyzed. Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/best-posting-time": { "post": { "operationId": "facebookBestPostingTime", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Find the best posting time", "description": "Deterministic interactions-by-publish-time analysis (UTC day and time band) over a bounded recent-post sample. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookBestPostingTimeReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-best-posting-time", "handle": "nasa", "analysis": { "basis": "interactions-by-publish-time-in-bounded-sample", "sampleSize": 12, "bestDayOfWeek": "Tuesday", "bestTimeBand": "morning (09:00-12:00 UTC)", "byDayOfWeek": [ { "day": "Tuesday", "posts": 4, "avgInteractions": 18200 } ], "byTimeBand": [ { "band": "morning (09:00-12:00 UTC)", "posts": 5, "avgInteractions": 17100 } ], "limitation": "Publish times are evaluated in UTC over the bounded sample; small samples make per-slot averages volatile. Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/hashtag-performance": { "post": { "operationId": "facebookHashtagPerformance", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Rank hashtag performance", "description": "Deterministic per-hashtag interaction averages versus the sample average over a bounded recent-post sample. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookHashtagPerformanceReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-hashtag-performance", "handle": "nasa", "analysis": { "basis": "hashtag-interactions-vs-sample-average", "sampleSize": 12, "sampleAvgInteractions": 15400, "hashtags": [ { "hashtag": "#artemis", "uses": 3, "avgInteractions": 24100, "performanceMultiple": 1.56 } ], "limitation": "Hashtag performance reflects only the bounded sample; correlation with a hashtag is not causation. Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/content-gap-analysis": { "post": { "operationId": "facebookContentGapAnalysis", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Analyze content format gaps", "description": "Deterministic format-mix versus format-engagement analysis identifying underused strong formats in a bounded recent-post sample. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookContentGapReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-content-gap-analysis", "handle": "nasa", "analysis": { "basis": "format-mix-vs-format-engagement-in-bounded-sample", "sampleSize": 12, "formats": [ { "format": "video", "sharePct": 16.7, "avgInteractions": 26100 }, { "format": "photo", "sharePct": 58.3, "avgInteractions": 14100 }, { "format": "link", "sharePct": 16.7, "avgInteractions": 9800 }, { "format": "text", "sharePct": 8.3, "avgInteractions": 7100 } ], "underusedStrongFormats": [ "video" ], "gaps": [ "The video format outperforms the sample average but is a small share of recent output." ], "limitation": "Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/audience-overlap": { "post": { "operationId": "facebookAudienceOverlap", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Estimate audience profile similarity", "description": "Deterministic audience-profile similarity estimate for two Pages from public signals. Does not measure actual shared-audience membership. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 26 bounded supplier records. Maximum result size: One report; hard maximum 26 records read and 4 Premium operations. Formula: requestUnits = 26 recordsRead; premiumRequestUnits = 4 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 26 Requests + 4 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "niche", "in": "query", "required": false, "description": "Content niche used by the deterministic model. Defaults to other. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "finance", "tech", "business", "education", "health", "beauty", "fashion", "fitness", "food", "travel", "lifestyle", "entertainment", "gaming", "other" ] }, "example": "education" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false }, { "name": "competitor_handle", "in": "query", "required": true, "description": "Public handle of the second Page. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nba" }, { "name": "competitor_niche", "in": "query", "required": false, "description": "Content niche of the second Page. Defaults to other. Send this value as a query Param.", "schema": { "type": "string", "enum": [ "finance", "tech", "business", "education", "health", "beauty", "fashion", "fitness", "food", "travel", "lifestyle", "entertainment", "gaming", "other" ] }, "example": "other" } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 26 bounded supplier records. Maximum result size: One report; hard maximum 26 records read and 4 Premium operations. Formula: requestUnits = 26 recordsRead; premiumRequestUnits = 4 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 26 Requests + 4 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=26; Premium Requests=4" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 26 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 26 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 4 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 4 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookAudienceOverlapReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 26 recordsRead; premiumRequestUnits = 4 boundedOperations. Before calling: 26 Requests + 4 Premium Requests maximum.", "value": { "surface": "facebook-audience-overlap", "handle": "nasa", "competitorHandle": "spacex", "analysis": { "audienceProfileSimilarityScore": 74, "similarityBand": "high", "isEstimate": true, "doesNotMeasureActualOverlap": true, "basis": "public-profile-similarity-signals", "components": { "nicheMatch": true, "sizeSimilarityPct": 62.1, "engagementSimilarityPct": 81.4, "cadenceSimilarityPct": 70 }, "limitation": "Similarity of public profile signals only - actual shared-audience membership is not observable from public data." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 26, "itemsPerUnit": 1, "requestUnits": 26, "premiumRequestUnits": 4, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 26 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 26 records read and 4 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 26 recordsRead; premiumRequestUnits = 4 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 26 Requests + 4 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=26; Premium Requests=4", "x-api-aha-results-returned: 26", "x-api-aha-request-units: 26", "x-api-aha-premium-request-units: 4", "x-api-aha-upstream-operations: 4", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "niche": "education", "narrate": "false", "competitor_handle": "nba", "competitor_niche": "other" }, "workedEstimate": "Before calling: 26 Requests + 4 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-comparison": { "post": { "operationId": "facebookPageComparison", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Compare two Pages", "description": "Deterministic operational comparison of two Pages (audience size, activity, maturity, engagement) with no valuation. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 26 bounded supplier records. Maximum result size: One report; hard maximum 26 records read and 4 Premium operations. Formula: requestUnits = 26 recordsRead; premiumRequestUnits = 4 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 26 Requests + 4 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false }, { "name": "competitor_handle", "in": "query", "required": true, "description": "Public handle of the second Page. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nba" } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 26 bounded supplier records. Maximum result size: One report; hard maximum 26 records read and 4 Premium operations. Formula: requestUnits = 26 recordsRead; premiumRequestUnits = 4 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 26 Requests + 4 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=26; Premium Requests=4" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 26 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 26 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 4 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 4 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookPageComparisonReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 26 recordsRead; premiumRequestUnits = 4 boundedOperations. Before calling: 26 Requests + 4 Premium Requests maximum.", "value": { "surface": "facebook-page-comparison", "handle": "nasa", "competitorHandle": "spacex", "analysis": { "basis": "same-public-page-signal-method-no-valuation", "primary": { "followerCount": 26700000, "postsLast30d": 18, "accountAgeYears": 15.4, "engagementRatePct": 0.19 }, "competitor": { "followerCount": 12800000, "postsLast30d": 9, "accountAgeYears": 12.1, "engagementRatePct": 0.24 }, "leaders": { "audienceSize": "primary", "activity": "primary", "maturity": "primary", "engagement": "competitor" } }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 26, "itemsPerUnit": 1, "requestUnits": 26, "premiumRequestUnits": 4, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 26 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 26 records read and 4 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 26 recordsRead; premiumRequestUnits = 4 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 26 Requests + 4 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=26; Premium Requests=4", "x-api-aha-results-returned: 26", "x-api-aha-request-units: 26", "x-api-aha-premium-request-units: 4", "x-api-aha-upstream-operations: 4", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false", "competitor_handle": "nba" }, "workedEstimate": "Before calling: 26 Requests + 4 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/posting-consistency-score": { "post": { "operationId": "facebookPostingConsistencyScore", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Score posting consistency", "description": "Deterministic inter-post gap statistics (mean gap, variability) scored over a bounded recent-post sample. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookPostingConsistencyReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-posting-consistency-score", "handle": "nasa", "analysis": { "postingConsistencyScore": 78, "classification": "steady", "basis": "inter-post-gap-statistics-in-bounded-sample", "sampleSize": 12, "meanGapDays": 2.4, "gapVariability": 0.42, "limitation": "Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/response-rate-score": { "post": { "operationId": "facebookResponseRateScore", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Score reply coverage", "description": "Deterministic reply-coverage score over a bounded public comment sample for one Page or post URL. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page or post URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookResponseRateReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-response-rate-score", "analysis": { "responseRateScore": 42, "replyCoveragePct": 41.7, "basis": "reply-coverage-in-bounded-comment-sample", "sampleSize": 12, "commentsWithReplies": 5, "limitation": "Reply coverage counts any public reply - the replier's identity (Page vs community) is not verified. Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/NASA/posts/pfbid02be4mckEcUxJ7L3smVozwjnm24x5jA93SFpDGTWqqHkyGewgaTvVbm6v1umYMZrb4l", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/review-response-analysis": { "post": { "operationId": "facebookReviewResponseAnalysis", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Analyze review responses", "description": "Deterministic reply-coverage, recommendation-share, and reaction analysis over a bounded public review-record sample. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Facebook Page URL. Send this value as a query Param.", "schema": { "type": "string", "format": "uri", "maxLength": 500 }, "example": "https://www.facebook.com/PikePlaceChowder/reviews" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookReviewResponseReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-review-response-analysis", "analysis": { "basis": "bounded-public-review-record-sample", "sampleSize": 12, "reviewsWithReplies": 4, "replyCoveragePct": 33.3, "recommendSharePct": 83.3, "avgReactionsPerReview": 2.1, "engagementLevel": "moderate", "limitation": "Reply presence does not verify the responder's identity, and recommendation share covers only reviews exposing that field. Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "url": "https://www.facebook.com/PikePlaceChowder/reviews", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/ad-presence-analysis": { "post": { "operationId": "facebookAdPresenceAnalysis", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Analyze ad presence", "description": "Deterministic ad-activity estimate from public Ad Library links on the Page record plus the sponsored-post share of a bounded recent-post sample. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookAdPresenceReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-ad-presence-analysis", "handle": "nasa", "analysis": { "adActivityLevel": "light", "basis": "page-record-ad-library-links-and-sponsored-post-share", "adLibraryLinkCount": 1, "sponsoredPostSharePct": 8.3, "sampleSize": 12, "limitation": "Detection uses public Ad Library links on the Page record and sponsored flags in the bounded post sample; ad spend, targeting, and full campaign inventory are not visible. Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/reaction-sentiment": { "post": { "operationId": "facebookReactionSentiment", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Score audience reaction sentiment", "description": "Deterministic sentiment index from the reaction-type distribution (love/care/haha/wow vs sad/angry) across a bounded recent-post sample, with a full per-reaction breakdown. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookReactionSentimentReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-reaction-sentiment", "handle": "nasa", "analysis": { "sentimentIndex": 22.4, "sentimentBand": "positive", "basis": "reaction-type-distribution-in-bounded-sample", "sampleSize": 12, "totalReactions": 48210, "emotionalEngagementPct": 26.1, "topReaction": "like", "breakdown": [ { "reaction": "like", "count": 35630, "sharePct": 73.9 }, { "reaction": "love", "count": 9420, "sharePct": 19.5 }, { "reaction": "wow", "count": 2110, "sharePct": 4.4 }, { "reaction": "haha", "count": 640, "sharePct": 1.3 }, { "reaction": "sad", "count": 260, "sharePct": 0.5 }, { "reaction": "angry", "count": 150, "sharePct": 0.3 } ], "limitation": "Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/page-authenticity": { "post": { "operationId": "facebookPageAuthenticity", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Screen page authenticity and trust signals", "description": "Deterministic trust screen over public page-record signals: verification, account age, external website, about section, and recent activity - a due-diligence check, not fraud detection. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookPageAuthenticityReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-page-authenticity", "handle": "nasa", "analysis": { "authenticityScore": 86, "band": "established", "basis": "public-page-trust-signals", "notFraudDetection": true, "signals": { "verified": true, "accountAgeYears": 16.4, "hasExternalWebsite": true, "hasAboutSection": true, "activeLast30d": true, "followerCount": 275000 }, "signalCoveragePct": 100, "flags": [], "limitation": "Trust signals from the public page record only - this is a due-diligence screen, not fraud or impersonation detection." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } }, "/api/facebook/video-performance": { "post": { "operationId": "facebookVideoPerformance", "tags": [ "💎 AI Intelligence (Premium)" ], "summary": "💎 Analyze video vs non-video performance", "description": "Deterministic video-format analysis over a bounded recent-post sample: video share, engagement multiple vs non-video posts, view totals, and a view-to-interaction rate. Send every input through the Params tab as query parameters; this operation has no request body. 💎 Premium endpoint: billed as a Premium Request (plus the records it reads as Requests).\n\nDefault result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Facebook Page handle, with or without a leading @. Send this value as a query Param.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "nasa" }, { "name": "narrate", "in": "query", "required": false, "description": "Request an optional qualitative explanation on an eligible paid plan. Structured numbers remain deterministic. Send this value as a query Param.", "schema": { "type": "boolean" }, "example": false } ], "x-billing-object": "Premium Requests", "x-transport-contract": "query-params-only", "responses": { "200": { "description": "Successful deterministic intelligence response. Default result size: One report reading at most 12 bounded supplier records. Maximum result size: One report; hard maximum 12 records read and 1 Premium operations. Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Pagination: unsupported. No cursor, page, offset, or continuation exists. A repeated call is a new analysis. Worked estimate before running: Before calling: 12 Requests + 1 Premium Requests maximum. Response usage metadata: Success exposes both meters, the bounded record draw, operation fan-out, and exact units. Safe example: One bounded target analysis with narrate=false. Non-2xx responses emit no custom usage header.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } }, "X-Facebook-Plan": { "description": "Resolved subscription plan.", "schema": { "type": "string" } }, "X-Facebook-Product": { "description": "Metered product object.", "schema": { "type": "string" } }, "X-Facebook-Quota-Limit": { "description": "Monthly allowance for the metered object.", "schema": { "type": "integer", "minimum": 0 } }, "X-Facebook-Quota-Remaining": { "description": "Remaining monthly allowance after this call.", "schema": { "type": "integer", "minimum": 0 } }, "X-RapidAPI-Billing": { "description": "Exact custom quota units for this successful response. Non-2xx responses omit this header.", "schema": { "type": "string" }, "example": "Requests=12; Premium Requests=1" }, "X-API-Aha-Results-Returned": { "description": "Customer-facing records, items, or reports delivered in this response. Not the Standard billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "X-API-Aha-Records-Read": { "description": "Supplier records read before customer-facing filtering or truncation. This is the Standard Requests billing basis.", "schema": { "type": "integer", "minimum": 0 }, "example": 12 }, "X-API-Aha-Request-Units": { "description": "Standard Requests charged by the response receipt.", "schema": { "type": "integer", "minimum": 1 }, "example": 12 }, "X-API-Aha-Bundle-Size": { "description": "Supplier records per Standard Request.", "schema": { "type": "integer", "enum": [ 1 ] }, "example": 1 }, "X-API-Aha-Unit-Formula": { "description": "Standard usage formula.", "schema": { "type": "string" }, "example": "1 Request per supplier record read" }, "X-API-Aha-Premium-Request-Units": { "description": "Premium Requests charged for bounded analysis operations.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 }, "X-API-Aha-Upstream-Operations": { "description": "Bounded analysis-operation count.", "schema": { "type": "integer", "minimum": 1, "maximum": 4 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookVideoPerformanceReport" }, "examples": { "successful": { "summary": "Successful bounded response", "description": "Formula: requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations. Before calling: 12 Requests + 1 Premium Requests maximum.", "value": { "surface": "facebook-video-performance", "handle": "nasa", "analysis": { "basis": "video-vs-nonvideo-interactions-in-bounded-sample", "sampleSize": 12, "videoPosts": 5, "videoSharePct": 41.7, "avgVideoInteractions": 6120.4, "avgNonVideoInteractions": 3384.9, "videoEngagementMultiple": 1.81, "totalVideoViews": 912400, "avgViewsPerVideo": 182480, "viewToInteractionRatePct": 3.35, "verdict": "video-outperforms", "limitation": "Computed from a bounded sample of recent public records, not the full history." }, "cached": false, "narration": null, "generatedAt": "2026-07-14T14:30:00.000Z", "usage": { "resultsReturned": 1, "recordsRead": 12, "itemsPerUnit": 1, "requestUnits": 12, "premiumRequestUnits": 1, "formula": "1 Request per supplier record read" } } } } } } }, "400": { "description": "Invalid or missing input.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "bad-input", "message": "Provide all required input fields.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "401": { "description": "RapidAPI gateway authentication failed.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "reason": "missing-or-invalid-key", "message": "Authentication required. Send a valid RapidAPI application key.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "404": { "description": "No usable public result was found for the target.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "reason": "target-not-found", "message": "No public result was found for that target.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "413": { "description": "The request input exceeded the supported size.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_INPUT", "reason": "body-too-large", "message": "The request input is too large.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "429": { "description": "Rate or monthly plan allowance exceeded.", "headers": { "Retry-After": { "description": "Suggested wait in seconds when supplied.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "reason": "rate-limited", "message": "The request limit was exceeded. Retry later or upgrade the plan.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "500": { "description": "Unexpected service failure.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL", "reason": "unexpected-error", "message": "The request could not be completed.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "502": { "description": "Public data collection did not finish within the bounded request window.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UPSTREAM", "reason": "provider_timeout", "message": "The public data provider did not finish within the bounded request window.", "request_id": "7ac8b1ef14de4f3b" } } } } }, "503": { "description": "The requested capability is temporarily unavailable.", "headers": { "X-Request-Id": { "description": "Support correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAVAILABLE", "reason": "temporarily-unavailable", "message": "The capability is temporarily unavailable.", "request_id": "7ac8b1ef14de4f3b" } } } } } }, "x-usage-units": { "classification": "Premium", "billingObject": "Premium Requests", "defaultResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report reading at most 12 bounded supplier records." }, "maximumResultSize": { "count": 1, "qualifier": "exactly", "unit": "analysis report", "detail": "One report; hard maximum 12 records read and 1 Premium operations." }, "requestedLimit": { "parameter": null, "default": "one bounded analysis", "acceptedMaximum": null, "effectiveMaximum": 1, "effectOnUnits": "No result limit exists; the route-specific record draw and operation fan-out are fixed and bounded." }, "pagination": { "supported": false, "parameters": [], "effectOnUnits": "No cursor, page, offset, or continuation exists. A repeated call is a new analysis." }, "formula": { "status": "verified-code-contract; live-receipt-required", "expression": "requestUnits = 12 recordsRead; premiumRequestUnits = 1 boundedOperations", "derivation": "Premium success dual-meters bounded supplier records read plus bounded analysis operations.", "requestedLimitEffect": "No caller-controlled limit or continuation exists.", "repeatedCallEffect": "Every uncached or cached successful buyer call applies the same disclosed formula.", "non2xxTreatment": "Non-2xx responses emit no custom usage header." }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "responseUsageMetadata": { "supported": true, "usageUnitHeader": "x-rapidapi-billing", "headers": [ "x-rapidapi-billing: Requests=12; Premium Requests=1", "x-api-aha-results-returned: 12", "x-api-aha-request-units: 12", "x-api-aha-premium-request-units: 1", "x-api-aha-upstream-operations: 1", "x-request-id" ], "detail": "Success exposes both meters, the bounded record draw, operation fan-out, and exact units." }, "safeLimitExample": "One bounded target analysis with narrate=false.", "calibration": { "required": true, "items": [ "Capture a live origin receipt and a RapidAPI gateway dual-meter receipt before publication." ] } }, "x-safe-example": { "queryParams": { "handle": "nasa", "narrate": "false" }, "workedEstimate": "Before calling: 12 Requests + 1 Premium Requests maximum.", "executionGate": "Verify the public target still resolves immediately before running." } } } }, "components": { "schemas": { "FacebookValuation": { "type": "object", "required": [ "estimateUsd", "rangeUsd", "confidence", "fakeFollowerFlag", "signalsUsed" ], "properties": { "estimateUsd": { "type": "number", "nullable": true }, "rangeUsd": { "type": "array", "nullable": true, "minItems": 2, "maxItems": 2, "items": { "type": "number" } }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "fakeFollowerFlag": { "type": "boolean" }, "signalsUsed": { "type": "object", "required": [ "followerCount", "engagementRate", "postsLast30d", "accountAgeYears", "niche", "hasShopSignal" ], "properties": { "followerCount": { "type": "number", "nullable": true }, "engagementRate": { "type": "number", "nullable": true }, "postsLast30d": { "type": "number", "nullable": true }, "accountAgeYears": { "type": "number", "nullable": true }, "niche": { "type": "string" }, "hasShopSignal": { "type": "boolean" } } }, "noSignalReason": { "type": "string" } } }, "FacebookNarration": { "type": "object", "required": [ "summary", "reasoning" ], "properties": { "summary": { "type": "string" }, "reasoning": { "type": "array", "items": { "type": "string" } } } }, "FacebookValueReport": { "type": "object", "required": [ "surface", "handle", "niche", "valuation", "narration", "cached", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-value" ] }, "handle": { "type": "string" }, "niche": { "type": "string" }, "valuation": { "$ref": "#/components/schemas/FacebookValuation" }, "narration": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/FacebookNarration" }, { "type": "object", "nullable": true } ] }, "cached": { "type": "boolean" }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookProfileReport": { "type": "object", "required": [ "surface", "handle", "followerCount", "accountAgeYears", "hasShopSignal", "cached", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-profile" ] }, "handle": { "type": "string" }, "followerCount": { "type": "number", "nullable": true }, "accountAgeYears": { "type": "number", "nullable": true }, "hasShopSignal": { "type": "boolean" }, "cached": { "type": "boolean" }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookPostsReport": { "type": "object", "required": [ "surface", "handle", "postsSampled", "avgLikesPerPost", "avgCommentsPerPost", "engagementRate", "cached", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-posts" ] }, "handle": { "type": "string" }, "postsSampled": { "type": "integer", "minimum": 0, "maximum": 12 }, "avgLikesPerPost": { "type": "number", "nullable": true }, "avgCommentsPerPost": { "type": "number", "nullable": true }, "engagementRate": { "type": "number", "nullable": true, "description": "Always null on this endpoint." }, "cached": { "type": "boolean" }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookCommentsReport": { "type": "object", "required": [ "surface", "target", "commentsSampled", "avgLikesPerComment", "avgRepliesPerComment", "cached", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-comments" ] }, "target": { "type": "string" }, "commentsSampled": { "type": "integer", "minimum": 0, "maximum": 50 }, "avgLikesPerComment": { "type": "number", "nullable": true }, "avgRepliesPerComment": { "type": "number", "nullable": true }, "cached": { "type": "boolean" }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookRawItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "author": { "type": "string" }, "category": { "type": "string" }, "location": { "type": "string" }, "currency": { "type": "string" }, "date": { "type": "string" }, "price": { "type": "number" }, "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "views": { "type": "number" }, "followers": { "type": "number" }, "attendees": { "type": "number" }, "mediaType": { "type": "string", "enum": [ "video", "photo" ], "description": "Present on filtered media lists: the deterministic media classification that matched the filter." } } }, "FacebookRawReport": { "type": "object", "required": [ "surface", "route", "count", "items", "cached", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "description": "Stable surface label such as facebook-marketplace or facebook-events." }, "route": { "type": "string", "enum": [ "posts-by-group", "marketplace", "marketplace-by-keyword", "marketplace-by-url", "post", "profile", "events", "events-by-url", "events-by-venue", "reels" ] }, "count": { "type": "integer", "minimum": 0, "maximum": 12 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FacebookRawItem" } }, "cached": { "type": "boolean" }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" }, "nextCursor": { "type": "string", "nullable": true, "description": "Always null: each call is one bounded snapshot collection and no continuation cursor is ever issued." } } }, "ErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": true, "required": [ "code", "reason", "message", "request_id" ], "properties": { "code": { "type": "string", "example": "BAD_INPUT" }, "reason": { "type": "string", "example": "bad-input" }, "message": { "type": "string", "example": "Provide all required input fields." }, "request_id": { "type": "string", "example": "7ac8b1ef14de4f3b" } } } } }, "FacebookIntelligenceNarration": { "type": "object", "additionalProperties": false, "required": [ "summary", "considerations" ], "properties": { "summary": { "type": "string" }, "considerations": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string" } } } }, "FacebookPageHealthReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-page-health-score" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "healthScore", "status", "signals", "priorities" ], "properties": { "healthScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "status": { "type": "string", "enum": [ "excellent", "good", "fair", "needs-attention" ] }, "signals": { "type": "object", "additionalProperties": false, "required": [ "followerCount", "accountAgeYears", "postsSampled", "avgInteractionsPerPost" ], "properties": { "followerCount": { "type": "integer", "nullable": true }, "accountAgeYears": { "type": "number", "nullable": true }, "postsSampled": { "type": "integer", "minimum": 0 }, "avgInteractionsPerPost": { "type": "number", "nullable": true } } }, "priorities": { "type": "array", "items": { "type": "string" } } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookGrowthForecastReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-growth-forecast" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "horizonDays", "currentFollowers", "projectedFollowers", "projectedNetGrowth", "monthlyGrowthRatePct", "forecastConfidence", "scenario" ], "properties": { "horizonDays": { "type": "integer", "enum": [ 30, 90, 180 ] }, "currentFollowers": { "type": "integer", "nullable": true }, "projectedFollowers": { "type": "integer", "nullable": true }, "projectedNetGrowth": { "type": "integer", "nullable": true }, "monthlyGrowthRatePct": { "type": "number", "nullable": true }, "forecastConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "scenario": { "type": "string", "enum": [ "baseline" ] } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookEngagementQualityReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-engagement-quality" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "engagementQualityScore", "grade", "engagementRatePct", "postsLast30d", "consistency", "qualitySignals" ], "properties": { "engagementQualityScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "excellent", "strong", "average", "weak" ] }, "engagementRatePct": { "type": "number", "nullable": true }, "postsLast30d": { "type": "integer", "nullable": true }, "consistency": { "type": "string", "enum": [ "inactive", "irregular", "consistent", "high-frequency", "unknown" ] }, "qualitySignals": { "type": "array", "items": { "type": "string" } } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookContentStrategyReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-content-strategy" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "objective", "currentPostsPerWeek", "recommendedPostsPerWeek", "benchmarkInteractionsPerPost", "formatPlan", "nextActions" ], "properties": { "objective": { "type": "string", "enum": [ "awareness", "engagement", "conversion" ] }, "currentPostsPerWeek": { "type": "number", "nullable": true }, "recommendedPostsPerWeek": { "type": "integer", "minimum": 0 }, "benchmarkInteractionsPerPost": { "type": "number", "nullable": true }, "formatPlan": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "format", "sharePct" ], "properties": { "format": { "type": "string", "enum": [ "short-video", "image-story", "community-prompt", "offer-proof" ] }, "sharePct": { "type": "integer", "minimum": 0, "maximum": 100 } } } }, "nextActions": { "type": "array", "items": { "type": "string" } } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookPostViralityReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-post-virality" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "observedInteractions", "baselineInteractionsPerPost", "breakoutMultiple", "viralityScore", "classification" ], "properties": { "observedInteractions": { "type": "integer", "minimum": 0 }, "baselineInteractionsPerPost": { "type": "number", "nullable": true }, "breakoutMultiple": { "type": "number", "nullable": true }, "viralityScore": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "classification": { "type": "string", "enum": [ "exceptional", "breakout", "typical", "below-baseline", "insufficient-baseline" ] } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookReviewSentimentReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-review-sentiment" ] }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "rating", "totalReviews", "sentimentIndex", "sentimentLabel", "confidence", "reviewVolume", "basis" ], "properties": { "rating": { "type": "number", "nullable": true }, "totalReviews": { "type": "integer", "nullable": true }, "sentimentIndex": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "sentimentLabel": { "type": "string", "enum": [ "positive", "mixed", "negative", "insufficient-data" ] }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "reviewVolume": { "type": "string", "enum": [ "high", "medium", "low", "none" ] }, "basis": { "type": "string", "enum": [ "aggregate-rating" ] } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookReputationReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-reputation-score" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "reputationScore", "status", "audienceTrustScore", "reviewSentimentIndex", "reviewCount", "riskFlags" ], "properties": { "reputationScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "status": { "type": "string", "enum": [ "excellent", "good", "watch", "high-risk" ] }, "audienceTrustScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "reviewSentimentIndex": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "reviewCount": { "type": "integer", "nullable": true }, "riskFlags": { "type": "array", "items": { "type": "string" } } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookAudienceQualityReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-audience-quality" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "audienceQualityScore", "authenticityRisk", "followerCount", "engagementRatePct", "activityLevel", "anomalies" ], "properties": { "audienceQualityScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "authenticityRisk": { "type": "string", "enum": [ "low", "medium", "high" ] }, "followerCount": { "type": "integer", "nullable": true }, "engagementRatePct": { "type": "number", "nullable": true }, "activityLevel": { "type": "string", "enum": [ "inactive", "irregular", "consistent", "high-frequency", "unknown" ] }, "anomalies": { "type": "array", "items": { "type": "string" } } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookPageInvestmentReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-page-investment-report" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "askingPriceUsd", "estimatedValueUsd", "estimatedValueRangeUsd", "estimatedUpsidePct", "pricePosition", "investmentScore", "decision", "valuationConfidence", "reviewSentimentIndex", "dueDiligenceFlags" ], "properties": { "askingPriceUsd": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "estimatedValueUsd": { "type": "number", "nullable": true }, "estimatedValueRangeUsd": { "type": "array", "minItems": 2, "maxItems": 2, "nullable": true, "items": { "type": "number" } }, "estimatedUpsidePct": { "type": "number", "nullable": true }, "pricePosition": { "type": "string", "enum": [ "below-estimate", "near-estimate", "above-estimate", "unavailable" ] }, "investmentScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "decision": { "type": "string", "enum": [ "attractive", "review-carefully", "high-risk" ] }, "valuationConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "reviewSentimentIndex": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "dueDiligenceFlags": { "type": "array", "items": { "type": "string" } } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookHealthReport": { "type": "object", "additionalProperties": false, "required": [ "ok", "service", "surface", "status", "checkedAt" ], "properties": { "ok": { "type": "boolean" }, "service": { "type": "string", "example": "api-aha" }, "surface": { "type": "string", "enum": [ "facebook-intelligence" ] }, "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "checkedAt": { "type": "string", "format": "date-time" } } }, "FacebookUsageReceipt": { "type": "object", "additionalProperties": false, "required": [ "resultsReturned", "recordsRead", "itemsPerUnit", "requestUnits", "formula" ], "properties": { "resultsReturned": { "type": "integer", "minimum": 0, "description": "Customer-facing records, items, or reports delivered in this response. This is not the Standard billing basis when supplier reads exceed delivered results." }, "recordsRead": { "type": "integer", "minimum": 0, "description": "Supplier records read for this response before customer-facing filtering or truncation. This is the Standard Requests billing basis." }, "itemsPerUnit": { "type": "integer", "enum": [ 1 ], "description": "Supplier records read per Standard Request unit." }, "requestUnits": { "type": "integer", "minimum": 1, "description": "Standard Requests charged for this successful response." }, "premiumRequestUnits": { "type": "integer", "minimum": 1, "description": "Premium analysis-operation units charged in addition to Standard Requests." }, "formula": { "type": "string", "enum": [ "1 Request per supplier record read" ] } } }, "FacebookExtractReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "route", "target", "data", "cached", "generatedAt", "usage" ], "properties": { "surface": { "type": "string" }, "route": { "type": "string" }, "target": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "cached": { "type": "boolean" }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookFilteredReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "route", "count", "items", "filteredFrom", "cached", "generatedAt", "usage" ], "properties": { "surface": { "type": "string" }, "route": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FacebookRawItem" } }, "filteredFrom": { "type": "integer", "minimum": 0 }, "cached": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookBrandSafetyReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-brand-safety-score" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "brandSafetyScore", "band", "basis", "sampleSize", "sponsoredSharePct", "externalLinkSharePct", "commentAnomalyCount", "activityLevel", "signals", "limitation" ], "properties": { "brandSafetyScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "band": { "type": "string", "enum": [ "low-risk", "moderate-risk", "elevated-risk", "insufficient-data" ] }, "basis": { "type": "string", "enum": [ "bounded-recent-post-signal-sample" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "sponsoredSharePct": { "type": "number", "nullable": true }, "externalLinkSharePct": { "type": "number", "nullable": true }, "commentAnomalyCount": { "type": "integer", "minimum": 0 }, "activityLevel": { "type": "string", "enum": [ "inactive", "irregular", "consistent", "high-frequency", "unknown" ] }, "signals": { "type": "array", "items": { "type": "string" } }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookCrisisDetectionReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-crisis-detection" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "crisisSignal", "basis", "sampleSize", "baselineCommentReactionRatio", "anomalousPosts", "engagementCollapseDetected", "observations", "limitation" ], "properties": { "crisisSignal": { "type": "string", "enum": [ "none", "watch", "elevated", "insufficient-data" ] }, "basis": { "type": "string", "enum": [ "comment-to-reaction-anomalies-in-bounded-sample" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "baselineCommentReactionRatio": { "type": "number", "nullable": true }, "anomalousPosts": { "type": "integer", "minimum": 0 }, "engagementCollapseDetected": { "type": "boolean" }, "observations": { "type": "array", "items": { "type": "string" } }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookBestPostingTimeReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-best-posting-time" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "basis", "sampleSize", "bestDayOfWeek", "bestTimeBand", "byDayOfWeek", "byTimeBand", "limitation" ], "properties": { "basis": { "type": "string", "enum": [ "interactions-by-publish-time-in-bounded-sample" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "bestDayOfWeek": { "type": "string", "nullable": true }, "bestTimeBand": { "type": "string", "nullable": true }, "byDayOfWeek": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "day", "posts", "avgInteractions" ], "properties": { "day": { "type": "string" }, "posts": { "type": "integer" }, "avgInteractions": { "type": "number" } } } }, "byTimeBand": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "band", "posts", "avgInteractions" ], "properties": { "band": { "type": "string" }, "posts": { "type": "integer" }, "avgInteractions": { "type": "number" } } } }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookHashtagPerformanceReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-hashtag-performance" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "basis", "sampleSize", "sampleAvgInteractions", "hashtags", "limitation" ], "properties": { "basis": { "type": "string", "enum": [ "hashtag-interactions-vs-sample-average" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "sampleAvgInteractions": { "type": "number", "nullable": true }, "hashtags": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "hashtag", "uses", "avgInteractions", "performanceMultiple" ], "properties": { "hashtag": { "type": "string" }, "uses": { "type": "integer" }, "avgInteractions": { "type": "number" }, "performanceMultiple": { "type": "number", "nullable": true } } } }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookContentGapReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-content-gap-analysis" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "basis", "sampleSize", "formats", "underusedStrongFormats", "gaps", "limitation" ], "properties": { "basis": { "type": "string", "enum": [ "format-mix-vs-format-engagement-in-bounded-sample" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "formats": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "format", "sharePct", "avgInteractions" ], "properties": { "format": { "type": "string", "enum": [ "video", "photo", "link", "text" ] }, "sharePct": { "type": "number" }, "avgInteractions": { "type": "number", "nullable": true } } } }, "underusedStrongFormats": { "type": "array", "items": { "type": "string" } }, "gaps": { "type": "array", "items": { "type": "string" } }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookAudienceOverlapReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "competitorHandle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-audience-overlap" ] }, "handle": { "type": "string" }, "competitorHandle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "audienceProfileSimilarityScore", "similarityBand", "isEstimate", "doesNotMeasureActualOverlap", "basis", "components", "limitation" ], "properties": { "audienceProfileSimilarityScore": { "type": "integer", "nullable": true }, "similarityBand": { "type": "string", "enum": [ "high", "moderate", "low", "insufficient-data" ] }, "isEstimate": { "type": "boolean", "enum": [ true ] }, "doesNotMeasureActualOverlap": { "type": "boolean", "enum": [ true ] }, "basis": { "type": "string", "enum": [ "public-profile-similarity-signals" ] }, "components": { "type": "object", "additionalProperties": false, "required": [ "nicheMatch", "sizeSimilarityPct", "engagementSimilarityPct", "cadenceSimilarityPct" ], "properties": { "nicheMatch": { "type": "boolean" }, "sizeSimilarityPct": { "type": "number", "nullable": true }, "engagementSimilarityPct": { "type": "number", "nullable": true }, "cadenceSimilarityPct": { "type": "number", "nullable": true } } }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookPageComparisonReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "competitorHandle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-page-comparison" ] }, "handle": { "type": "string" }, "competitorHandle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "basis", "primary", "competitor", "leaders" ], "properties": { "basis": { "type": "string", "enum": [ "same-public-page-signal-method-no-valuation" ] }, "primary": { "type": "object", "additionalProperties": false, "required": [ "followerCount", "postsLast30d", "accountAgeYears", "engagementRatePct" ], "properties": { "followerCount": { "type": "integer", "nullable": true }, "postsLast30d": { "type": "integer", "nullable": true }, "accountAgeYears": { "type": "number", "nullable": true }, "engagementRatePct": { "type": "number", "nullable": true } } }, "competitor": { "type": "object", "additionalProperties": false, "required": [ "followerCount", "postsLast30d", "accountAgeYears", "engagementRatePct" ], "properties": { "followerCount": { "type": "integer", "nullable": true }, "postsLast30d": { "type": "integer", "nullable": true }, "accountAgeYears": { "type": "number", "nullable": true }, "engagementRatePct": { "type": "number", "nullable": true } } }, "leaders": { "type": "object", "additionalProperties": false, "required": [ "audienceSize", "activity", "maturity", "engagement" ], "properties": { "audienceSize": { "type": "string", "enum": [ "primary", "competitor", "tie", "insufficient-data" ] }, "activity": { "type": "string", "enum": [ "primary", "competitor", "tie", "insufficient-data" ] }, "maturity": { "type": "string", "enum": [ "primary", "competitor", "tie", "insufficient-data" ] }, "engagement": { "type": "string", "enum": [ "primary", "competitor", "tie", "insufficient-data" ] } } } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookPostingConsistencyReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-posting-consistency-score" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "postingConsistencyScore", "classification", "basis", "sampleSize", "meanGapDays", "gapVariability", "limitation" ], "properties": { "postingConsistencyScore": { "type": "integer", "nullable": true }, "classification": { "type": "string", "enum": [ "metronomic", "steady", "irregular", "sporadic", "insufficient-data" ] }, "basis": { "type": "string", "enum": [ "inter-post-gap-statistics-in-bounded-sample" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "meanGapDays": { "type": "number", "nullable": true }, "gapVariability": { "type": "number", "nullable": true }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookResponseRateReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-response-rate-score" ] }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "responseRateScore", "replyCoveragePct", "basis", "sampleSize", "commentsWithReplies", "limitation" ], "properties": { "responseRateScore": { "type": "integer", "nullable": true }, "replyCoveragePct": { "type": "number", "nullable": true }, "basis": { "type": "string", "enum": [ "reply-coverage-in-bounded-comment-sample" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "commentsWithReplies": { "type": "integer", "minimum": 0 }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookReviewResponseReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-review-response-analysis" ] }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "basis", "sampleSize", "reviewsWithReplies", "replyCoveragePct", "recommendSharePct", "avgReactionsPerReview", "engagementLevel", "limitation" ], "properties": { "basis": { "type": "string", "enum": [ "bounded-public-review-record-sample" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "reviewsWithReplies": { "type": "integer", "minimum": 0 }, "replyCoveragePct": { "type": "number", "nullable": true }, "recommendSharePct": { "type": "number", "nullable": true }, "avgReactionsPerReview": { "type": "number", "nullable": true }, "engagementLevel": { "type": "string", "enum": [ "high", "moderate", "low", "insufficient-data" ] }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookAdPresenceReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-ad-presence-analysis" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "adActivityLevel", "basis", "adLibraryLinkCount", "sponsoredPostSharePct", "sampleSize", "limitation" ], "properties": { "adActivityLevel": { "type": "string", "enum": [ "none-detected", "light", "active", "heavy", "insufficient-data" ] }, "basis": { "type": "string", "enum": [ "page-record-ad-library-links-and-sponsored-post-share" ] }, "adLibraryLinkCount": { "type": "integer", "nullable": true }, "sponsoredPostSharePct": { "type": "number", "nullable": true }, "sampleSize": { "type": "integer", "minimum": 0 }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookReactionSentimentReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-reaction-sentiment" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "sentimentIndex", "sentimentBand", "basis", "sampleSize", "totalReactions", "emotionalEngagementPct", "topReaction", "breakdown", "limitation" ], "properties": { "sentimentIndex": { "type": "number", "nullable": true }, "sentimentBand": { "type": "string", "enum": [ "positive", "neutral", "mixed", "negative", "insufficient-data" ] }, "basis": { "type": "string", "enum": [ "reaction-type-distribution-in-bounded-sample" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "totalReactions": { "type": "integer", "minimum": 0 }, "emotionalEngagementPct": { "type": "number", "nullable": true }, "topReaction": { "type": "string", "nullable": true }, "breakdown": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "reaction", "count", "sharePct" ], "properties": { "reaction": { "type": "string" }, "count": { "type": "integer" }, "sharePct": { "type": "number" } } } }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookPageAuthenticityReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-page-authenticity" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "authenticityScore", "band", "basis", "notFraudDetection", "signals", "signalCoveragePct", "flags", "limitation" ], "properties": { "authenticityScore": { "type": "integer", "nullable": true }, "band": { "type": "string", "enum": [ "established", "credible", "limited-signals", "insufficient-data" ] }, "basis": { "type": "string", "enum": [ "public-page-trust-signals" ] }, "notFraudDetection": { "type": "boolean", "enum": [ true ] }, "signals": { "type": "object", "additionalProperties": false, "required": [ "verified", "accountAgeYears", "hasExternalWebsite", "hasAboutSection", "activeLast30d", "followerCount" ], "properties": { "verified": { "type": "boolean", "nullable": true }, "accountAgeYears": { "type": "number", "nullable": true }, "hasExternalWebsite": { "type": "boolean" }, "hasAboutSection": { "type": "boolean" }, "activeLast30d": { "type": "boolean", "nullable": true }, "followerCount": { "type": "integer", "nullable": true } } }, "signalCoveragePct": { "type": "number" }, "flags": { "type": "array", "items": { "type": "string" } }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } }, "FacebookVideoPerformanceReport": { "type": "object", "additionalProperties": false, "required": [ "surface", "handle", "analysis", "cached", "narration", "generatedAt", "usage" ], "properties": { "surface": { "type": "string", "enum": [ "facebook-video-performance" ] }, "handle": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": false, "required": [ "basis", "sampleSize", "videoPosts", "videoSharePct", "avgVideoInteractions", "avgNonVideoInteractions", "videoEngagementMultiple", "totalVideoViews", "avgViewsPerVideo", "viewToInteractionRatePct", "verdict", "limitation" ], "properties": { "basis": { "type": "string", "enum": [ "video-vs-nonvideo-interactions-in-bounded-sample" ] }, "sampleSize": { "type": "integer", "minimum": 0 }, "videoPosts": { "type": "integer", "minimum": 0 }, "videoSharePct": { "type": "number", "nullable": true }, "avgVideoInteractions": { "type": "number", "nullable": true }, "avgNonVideoInteractions": { "type": "number", "nullable": true }, "videoEngagementMultiple": { "type": "number", "nullable": true }, "totalVideoViews": { "type": "integer", "nullable": true }, "avgViewsPerVideo": { "type": "number", "nullable": true }, "viewToInteractionRatePct": { "type": "number", "nullable": true }, "verdict": { "type": "string", "enum": [ "video-outperforms", "comparable", "video-underperforms", "insufficient-data" ] }, "limitation": { "type": "string" } } }, "cached": { "type": "boolean" }, "narration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FacebookIntelligenceNarration" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/FacebookUsageReceipt" } } } } } }