{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Adspy API", "version": "1.0.0", "summary": "Public ad and organic post research, server to server.", "description": "The Adspy REST API reads Adspy's library of public Meta and Google ads and of brands' organic TikTok and YouTube posts: brands, creatives, AI analyses, X-Rays, Full Analyses, social reports, comparisons, collections and exports. It is part of Adspy Enterprise, and partner products reach it with partner keys. Instagram is not available in the API. Errors are RFC 9457 problem details; lists page with opaque cursors; every POST takes an Idempotency-Key.", "contact": { "name": "Adspy", "email": "info@adspy.sh", "url": "https://www.adspy.sh/docs/api" }, "termsOfService": "https://www.adspy.sh/terms" }, "externalDocs": { "description": "Adspy API documentation", "url": "https://www.adspy.sh/docs/api" }, "servers": [ { "url": "https://www.adspy.sh/api", "description": "Adspy" } ], "security": [ { "apiKey": [] }, { "partnerKey": [] } ], "tags": [ { "name": "Brands" }, { "name": "Reports" }, { "name": "Social" }, { "name": "Creatives" }, { "name": "Fetches" }, { "name": "Collections" }, { "name": "Exports" }, { "name": "Usage" } ], "paths": { "/v1/brands": { "get": { "operationId": "listBrands", "summary": "Search brands", "description": "Brands in Adspy's library, by name. Each brand carries its key (brand_key), which every brand route takes. `social_only_brands` lists brands Adspy knows only from a TikTok or YouTube account matching the query (first page only). Needs the read permission.", "tags": [ "Brands" ], "x-permission": "read", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Part of the brand's name. Without it, brands are listed by name.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100 (default 20).", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Send it with the same filters; it is valid for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 600 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "brand_key": { "type": "string" }, "name": { "type": "string" }, "logo_url": { "description": "A signed media link (21 days).", "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "ad_platforms": { "type": "array", "items": { "type": "string" }, "description": "The ad libraries the brand runs ads in: meta, google." }, "industry": { "type": [ "string", "null" ] }, "creative_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "social": { "anyOf": [ { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." } }, "posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Posts Adspy holds for these accounts; null when unknown or when it would include Instagram." } }, "required": [ "platforms", "posts" ], "additionalProperties": false }, { "type": "null" } ], "description": "The brand's collected TikTok and YouTube accounts, or null." } }, "required": [ "brand_key", "name", "logo_url", "website", "ad_platforms", "industry", "creative_count", "social" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Send it as `cursor`, with the same filters, for the next page.", "type": [ "string", "null" ] }, "total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "social_only_brands": { "type": "array", "items": { "type": "object", "properties": { "brand_key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "social": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." } } }, "required": [ "platforms" ], "additionalProperties": false }, "accounts": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "An account: account_id, platform, handle, profile_url." } } }, "required": [ "brand_key", "name", "social", "accounts" ], "additionalProperties": false } }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "has_more", "next_cursor", "total", "social_only_brands" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). invalid_cursor: Invalid cursor (https://www.adspy.sh/docs/api/errors/invalid-cursor)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "invalid_cursor" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/brands/{brand_key}": { "get": { "operationId": "getBrand", "summary": "Get a brand", "description": "One brand: its name, website, ad platforms, industry, creative count and collected social accounts. Needs the read permission.", "tags": [ "Brands" ], "x-permission": "read", "parameters": [ { "name": "brand_key", "in": "path", "required": true, "description": "The brand's key, from GET /v1/brands.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "brand_key": { "type": "string" }, "name": { "type": "string" }, "logo_url": { "description": "A signed media link (21 days).", "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "ad_platforms": { "type": "array", "items": { "type": "string" }, "description": "The ad libraries the brand runs ads in: meta, google." }, "industry": { "type": [ "string", "null" ] }, "creative_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "social": { "anyOf": [ { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." } }, "posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Posts Adspy holds for these accounts; null when unknown or when it would include Instagram." } }, "required": [ "platforms", "posts" ], "additionalProperties": false }, { "type": "null" } ], "description": "The brand's collected TikTok and YouTube accounts, or null." }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "brand_key", "name", "logo_url", "website", "ad_platforms", "industry", "creative_count", "social" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/brands/{brand_key}/creatives": { "get": { "operationId": "listBrandCreatives", "summary": "List a brand's creatives", "description": "The brand's creatives with the creative search filters. Pages can be shorter than `limit`: follow `has_more`. Needs the read permission.", "tags": [ "Brands" ], "x-permission": "read", "parameters": [ { "name": "brand_key", "in": "path", "required": true, "description": "The brand's key, from GET /v1/brands.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "query", "in": "query", "required": false, "description": "Words to find, in the scope chosen.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "scope", "in": "query", "required": false, "description": "Where `query` is matched (default all).", "schema": { "default": "all", "type": "string", "enum": [ "all", "ad_copy", "content_transcript", "visual_analysis", "all_keywords", "hooks" ] } }, { "name": "platform", "in": "query", "required": false, "description": "The ad library: meta (Facebook, Instagram and Messenger placements) or google (Search, YouTube, Display).", "schema": { "type": "string", "enum": [ "all", "meta", "google" ] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "image", "video", "carousel" ] } }, { "name": "status", "in": "query", "required": false, "description": "Whether the library last saw the ad running.", "schema": { "type": "string", "enum": [ "all", "active", "inactive" ] } }, { "name": "sort", "in": "query", "required": false, "description": "newest or oldest first sighting, or longest running (default newest).", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "longest" ] } }, { "name": "tags", "in": "query", "required": false, "description": "AI tags the creative must all carry, comma-separated, e.g. hook_type:Question.", "schema": { "type": "string", "maxLength": 5200 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 30 } }, { "name": "min_days_active", "in": "query", "required": false, "description": "Only creatives seen running for at least this many days.", "schema": { "type": "integer", "minimum": 0, "maximum": 36500 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100 (default 20).", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Send it with the same filters; it is valid for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 600 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The creative's id (its media hash)." }, "brand_key": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "brand_logo_url": { "type": [ "string", "null" ] }, "platform": { "description": "meta or google.", "type": [ "string", "null" ] }, "format": { "description": "image, video or carousel.", "type": [ "string", "null" ] }, "media_url": { "description": "The creative's media: a signed link, valid 21 days.", "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "media_urls": { "type": "array", "items": { "type": "string" } }, "external_watch_url": { "description": "A YouTube link for Google video ads, when the file is not stored.", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "first_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "last_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "status": { "description": "active, inactive or unknown.", "type": [ "string", "null" ] }, "days_active": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ads_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Source ads that run this creative." }, "tags": { "type": "array", "items": { "type": "string" } }, "language": { "type": [ "string", "null" ] }, "media_availability": { "type": [ "string", "null" ] }, "media_unavailable_reason": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] } }, "required": [ "id", "brand_key", "brand_name", "brand_logo_url", "platform", "format", "media_url", "poster_url", "media_urls", "external_watch_url", "title", "body", "first_seen", "last_seen", "status", "days_active", "ads_count", "tags", "language", "media_availability", "media_unavailable_reason", "transcript" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Send it as `cursor`, with the same filters, for the next page.", "type": [ "string", "null" ] }, "total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "has_more", "next_cursor", "total" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). invalid_cursor: Invalid cursor (https://www.adspy.sh/docs/api/errors/invalid-cursor)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "invalid_cursor" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "timeout: Timeout (https://www.adspy.sh/docs/api/errors/timeout)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/brands/{brand_key}/xray": { "get": { "operationId": "getBrandXray", "summary": "Get a brand's X-Ray", "description": "The brand's X-Ray: the observed creative strategy (formats, hooks, funnel, longevity, audience estimates, destinations, changes) over a range, from public creatives. Evidence, not ad performance. A report is reused for 24 hours. Needs the actions permission.", "tags": [ "Reports" ], "x-permission": "actions", "parameters": [ { "name": "brand_key", "in": "path", "required": true, "description": "The brand's key, from GET /v1/brands.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "range", "in": "query", "required": false, "description": "The window of first sightings the report covers (default 90d).", "schema": { "default": "90d", "type": "string", "enum": [ "30d", "90d", "180d", "all" ] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "instagram_excluded": { "type": "boolean" }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "additionalProperties": {}, "description": "The X-Ray report." } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached). payment_required: Payment required (https://www.adspy.sh/docs/api/errors/payment-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached", "payment_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "timeout: Timeout (https://www.adspy.sh/docs/api/errors/timeout)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/brands/{brand_key}/social": { "get": { "operationId": "getBrandSocial", "summary": "Get a brand's social report", "description": "The brand's organic TikTok and YouTube report: accounts, cadence, views and engagement per view with confidence intervals, breakouts, paid reach (listed apart from organic numbers) and posts run as ads. Instagram is left out; aggregates over all platforms are null when the brand also has Instagram (`instagram_excluded`). Needs the actions permission.", "tags": [ "Reports" ], "x-permission": "actions", "parameters": [ { "name": "brand_key", "in": "path", "required": true, "description": "The brand's key, from GET /v1/brands.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "range", "in": "query", "required": false, "description": "The statistics window: the last 30 or 90 days (default 90d).", "schema": { "default": "90d", "type": "string", "enum": [ "30d", "90d" ] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "instagram_excluded": { "type": "boolean" }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "additionalProperties": {}, "description": "The social report." } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached). payment_required: Payment required (https://www.adspy.sh/docs/api/errors/payment-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached", "payment_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/brands/{brand_key}/posts-run-as-ads": { "get": { "operationId": "listPostsRunAsAds", "summary": "List a brand's posts run as ads", "description": "Pairs of a brand's organic post and the ad cut from it (or the ad later posted organically), matched by media. Instagram pairs are left out; without `platform`, `summary` is null when the brand also has Instagram. Needs the read permission.", "tags": [ "Social" ], "x-permission": "read", "parameters": [ { "name": "brand_key", "in": "path", "required": true, "description": "The brand's key, from GET /v1/brands.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "range", "in": "query", "required": false, "description": "Posts published in this window (default 90d).", "schema": { "default": "90d", "type": "string", "enum": [ "30d", "90d", "180d", "all" ] } }, { "name": "platform", "in": "query", "required": false, "description": "tiktok or youtube. Instagram is not available in the API.", "schema": { "type": "string", "enum": [ "tiktok", "youtube" ] } }, { "name": "direction", "in": "query", "required": false, "description": "organic_to_paid: posts later run as ads. paid_to_organic: ads later posted organically.", "schema": { "default": "organic_to_paid", "type": "string", "enum": [ "organic_to_paid", "paid_to_organic", "all" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100 (default 20).", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Send it with the same filters; it is valid for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 600 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "pair_id": { "type": "string" }, "direction": { "type": "string" }, "lag_days": { "type": [ "number", "null" ] }, "match": { "type": [ "string", "null" ] }, "post": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "post_id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "brand_key": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "published_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "published_at_approx": { "type": [ "boolean", "null" ] }, "format": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "duration_sec": { "type": [ "number", "null" ] }, "thumb_url": { "type": [ "string", "null" ] }, "counts": { "type": "object", "properties": { "views": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "comments": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "shares": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "saves": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "views", "likes", "comments", "shares", "saves" ], "additionalProperties": false, "description": "Public counts; null when the platform does not show one (never zero)." }, "counts_rounded": { "type": [ "boolean", "null" ] }, "counts_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "engagement_rate": { "description": "Engagement per view (posts with 50+ views).", "type": [ "number", "null" ] }, "reach": { "description": "breakout, paid_reach or null (90-day statistics).", "type": [ "string", "null" ] }, "ran_as_ad": { "type": [ "boolean", "null" ] }, "promoted_flag": { "type": [ "boolean", "null" ] }, "pinned": { "type": [ "boolean", "null" ] }, "deleted_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] } }, "required": [ "id", "platform", "post_id", "account_id", "handle", "brand_key", "permalink", "published_at", "published_at_approx", "format", "title", "caption", "hashtags", "duration_sec", "thumb_url", "counts", "counts_rounded", "counts_at", "engagement_rate", "reach", "ran_as_ad", "promoted_flag", "pinned", "deleted_at" ], "additionalProperties": {} }, "ad": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The ad: creative_id, source, ad_type, ad_first_seen, in_library, creative." } }, "required": [ "pair_id", "direction", "lag_days", "match", "post", "ad" ], "additionalProperties": {} } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Send it as `cursor`, with the same filters, for the next page.", "type": [ "string", "null" ] }, "summary": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "handle": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "profile_url": { "type": [ "string", "null" ] }, "verified": { "type": [ "boolean", "null" ] }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "followers_rounded": { "type": [ "boolean", "null" ] }, "posts_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "history_complete": { "type": [ "boolean", "null" ] }, "last_success_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "status": { "type": [ "string", "null" ] } }, "required": [ "account_id", "platform", "handle", "display_name", "profile_url", "verified", "followers", "followers_rounded", "posts_count", "history_complete", "last_success_at", "status" ], "additionalProperties": false } }, "matching": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "instagram_excluded": { "type": "boolean" }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "has_more", "next_cursor", "summary", "accounts", "matching" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). invalid_cursor: Invalid cursor (https://www.adspy.sh/docs/api/errors/invalid-cursor)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "invalid_cursor" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "instagram_not_in_api: Instagram is not available in the API (https://www.adspy.sh/docs/api/errors/instagram-not-in-api)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "instagram_not_in_api" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/brands/{brand_key}/full-analysis": { "post": { "operationId": "createFullAnalysis", "summary": "Run a brand's Full Analysis", "description": "The Brand Full Analysis: the ads, the organic posts and the links between them, with every number's n, confidence interval and test, multiple-testing corrected. Evidence from public data, never spend or results. Reused for 24 hours. When the brand has Instagram, Instagram is left out and the cross-platform aggregates are withheld (`instagram_excluded`). Needs the actions permission.", "tags": [ "Reports" ], "x-permission": "actions", "parameters": [ { "name": "brand_key", "in": "path", "required": true, "description": "The brand's key, from GET /v1/brands.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "default": "90d", "description": "The ads' mix, hooks and destinations cover this range; each finding states its own window (default 90d).", "type": "string", "enum": [ "30d", "90d", "180d", "all" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "instagram_excluded": { "type": "boolean" }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "additionalProperties": {}, "description": "The Full Analysis report." } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). idempotency_key_required: Idempotency key required (https://www.adspy.sh/docs/api/errors/idempotency-key-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "idempotency_key_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached). payment_required: Payment required (https://www.adspy.sh/docs/api/errors/payment-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached", "payment_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict: Idempotency conflict (https://www.adspy.sh/docs/api/errors/idempotency-conflict). operation_in_progress: Operation in progress (https://www.adspy.sh/docs/api/errors/operation-in-progress)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "idempotency_conflict", "operation_in_progress" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "payload_too_large: Payload too large (https://www.adspy.sh/docs/api/errors/payload-too-large)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payload_too_large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "unsupported_media_type: Unsupported media type (https://www.adspy.sh/docs/api/errors/unsupported-media-type)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unsupported_media_type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "timeout: Timeout (https://www.adspy.sh/docs/api/errors/timeout)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/creatives": { "get": { "operationId": "searchCreatives", "summary": "Search creatives", "description": "Meta and Google creatives in Adspy's library, with filters. Live offset pages, not a fixed snapshot: a page can repeat or skip an item when the library changes between pages. Needs the read permission.", "tags": [ "Creatives" ], "x-permission": "read", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Words to find, in the scope chosen.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "scope", "in": "query", "required": false, "description": "Where `query` is matched (default all).", "schema": { "default": "all", "type": "string", "enum": [ "all", "ad_copy", "content_transcript", "visual_analysis", "all_keywords", "hooks" ] } }, { "name": "platform", "in": "query", "required": false, "description": "The ad library: meta (Facebook, Instagram and Messenger placements) or google (Search, YouTube, Display).", "schema": { "type": "string", "enum": [ "all", "meta", "google" ] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "image", "video", "carousel" ] } }, { "name": "status", "in": "query", "required": false, "description": "Whether the library last saw the ad running.", "schema": { "type": "string", "enum": [ "all", "active", "inactive" ] } }, { "name": "sort", "in": "query", "required": false, "description": "newest or oldest first sighting, or longest running (default newest).", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "longest" ] } }, { "name": "tags", "in": "query", "required": false, "description": "AI tags the creative must all carry, comma-separated, e.g. hook_type:Question.", "schema": { "type": "string", "maxLength": 5200 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 30 } }, { "name": "min_days_active", "in": "query", "required": false, "description": "Only creatives seen running for at least this many days.", "schema": { "type": "integer", "minimum": 0, "maximum": 36500 } }, { "name": "brand_key", "in": "query", "required": false, "description": "Only this brand's creatives.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "brand_keys", "in": "query", "required": false, "description": "Only these brands' creatives, comma-separated (up to 100).", "schema": { "type": "string", "maxLength": 26000 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100 (default 20).", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Send it with the same filters; it is valid for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 600 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The creative's id (its media hash)." }, "brand_key": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "brand_logo_url": { "type": [ "string", "null" ] }, "platform": { "description": "meta or google.", "type": [ "string", "null" ] }, "format": { "description": "image, video or carousel.", "type": [ "string", "null" ] }, "media_url": { "description": "The creative's media: a signed link, valid 21 days.", "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "media_urls": { "type": "array", "items": { "type": "string" } }, "external_watch_url": { "description": "A YouTube link for Google video ads, when the file is not stored.", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "first_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "last_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "status": { "description": "active, inactive or unknown.", "type": [ "string", "null" ] }, "days_active": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ads_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Source ads that run this creative." }, "tags": { "type": "array", "items": { "type": "string" } }, "language": { "type": [ "string", "null" ] }, "media_availability": { "type": [ "string", "null" ] }, "media_unavailable_reason": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] } }, "required": [ "id", "brand_key", "brand_name", "brand_logo_url", "platform", "format", "media_url", "poster_url", "media_urls", "external_watch_url", "title", "body", "first_seen", "last_seen", "status", "days_active", "ads_count", "tags", "language", "media_availability", "media_unavailable_reason", "transcript" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Send it as `cursor`, with the same filters, for the next page.", "type": [ "string", "null" ] }, "total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "has_more", "next_cursor", "total" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). invalid_cursor: Invalid cursor (https://www.adspy.sh/docs/api/errors/invalid-cursor)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "invalid_cursor" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "timeout: Timeout (https://www.adspy.sh/docs/api/errors/timeout)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/creatives/by-meaning": { "get": { "operationId": "searchCreativesByMeaning", "summary": "Search creatives by meaning", "description": "Creatives whose transcript says what you describe, closest meaning first, in any language and even with other words. A creative without a transcript is never found here: use the creative search for exact words, ad copy or a brand's full list. Filters apply before ordering. Status, tags and days active are not offered here. Needs the read permission.", "tags": [ "Creatives" ], "x-permission": "read", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What the ads should say, in plain words and any language: an idea, an angle, a pain point.", "schema": { "type": "string", "minLength": 3, "maxLength": 300 } }, { "name": "brand_key", "in": "query", "required": false, "description": "Only this brand's creatives.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "brand_keys", "in": "query", "required": false, "description": "Only these brands' creatives, comma-separated (up to 100).", "schema": { "type": "string", "maxLength": 26000 } }, { "name": "platform", "in": "query", "required": false, "description": "The ad library: meta (Facebook, Instagram and Messenger placements) or google (Search, YouTube, Display).", "schema": { "type": "string", "enum": [ "all", "meta", "google" ] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "image", "video", "carousel" ] } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 30 } }, { "name": "since", "in": "query", "required": false, "description": "Only creatives first seen on or after this day, e.g. 2026-09-01.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100 (default 20).", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Send it with the same filters; it is valid for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 600 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The creative's id (its media hash)." }, "brand_key": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "brand_logo_url": { "type": [ "string", "null" ] }, "platform": { "description": "meta or google.", "type": [ "string", "null" ] }, "format": { "description": "image, video or carousel.", "type": [ "string", "null" ] }, "media_url": { "description": "The creative's media: a signed link, valid 21 days.", "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "media_urls": { "type": "array", "items": { "type": "string" } }, "external_watch_url": { "description": "A YouTube link for Google video ads, when the file is not stored.", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "first_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "last_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "status": { "description": "active, inactive or unknown.", "type": [ "string", "null" ] }, "days_active": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ads_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Source ads that run this creative." }, "tags": { "type": "array", "items": { "type": "string" } }, "language": { "type": [ "string", "null" ] }, "media_availability": { "type": [ "string", "null" ] }, "media_unavailable_reason": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] }, "match_score": { "type": "number", "description": "How close the meaning is, from 0 to 1. Never a measure of results." } }, "required": [ "id", "brand_key", "brand_name", "brand_logo_url", "platform", "format", "media_url", "poster_url", "media_urls", "external_watch_url", "title", "body", "first_seen", "last_seen", "status", "days_active", "ads_count", "tags", "language", "media_availability", "media_unavailable_reason", "transcript", "match_score" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Send it as `cursor`, with the same filters, for the next page.", "type": [ "string", "null" ] }, "total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "has_more", "next_cursor", "total" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). invalid_cursor: Invalid cursor (https://www.adspy.sh/docs/api/errors/invalid-cursor)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "invalid_cursor" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "timeout: Timeout (https://www.adspy.sh/docs/api/errors/timeout)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/creatives/{id}": { "get": { "operationId": "getCreative", "summary": "Get a creative", "description": "One creative with its transcript, source ads (variants), hook, AI tags, CTA and landing pages. Needs the read permission.", "tags": [ "Creatives" ], "x-permission": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The creative id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The creative's id (its media hash)." }, "brand_key": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "brand_logo_url": { "type": [ "string", "null" ] }, "platform": { "description": "meta or google.", "type": [ "string", "null" ] }, "format": { "description": "image, video or carousel.", "type": [ "string", "null" ] }, "media_url": { "description": "The creative's media: a signed link, valid 21 days.", "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "media_urls": { "type": "array", "items": { "type": "string" } }, "external_watch_url": { "description": "A YouTube link for Google video ads, when the file is not stored.", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "first_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "last_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "status": { "description": "active, inactive or unknown.", "type": [ "string", "null" ] }, "days_active": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ads_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Source ads that run this creative." }, "tags": { "type": "array", "items": { "type": "string" } }, "language": { "type": [ "string", "null" ] }, "media_availability": { "type": [ "string", "null" ] }, "media_unavailable_reason": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] }, "transcript_status": { "type": [ "string", "null" ] }, "transcript_parts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "text": { "type": "string" } }, "required": [ "kind", "label", "text" ], "additionalProperties": false } }, "variants": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "A source ad: ad_id, source, status, activation_date, deactivation_date, title, body, related_creative_ids, source_url, placements, frames." }, "description": "The source ads that run this creative, newest first." }, "variants_limited": { "type": "boolean" }, "variants_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "active_variants_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hook": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The opening: type, description, timestamp, why." }, { "type": "null" } ] }, "ai_tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "tags": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "tag, label, value, description" } } }, "required": [ "id", "label", "tags" ], "additionalProperties": false } }, "cta": { "type": [ "string", "null" ] }, "landing_page_url": { "type": [ "string", "null" ] }, "overview": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Counted over the source ads read: ctas, landing_pages, landing_pages_total, placements, estimated_countries." }, { "type": "null" } ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "id", "brand_key", "brand_name", "brand_logo_url", "platform", "format", "media_url", "poster_url", "media_urls", "external_watch_url", "title", "body", "first_seen", "last_seen", "status", "days_active", "ads_count", "tags", "language", "media_availability", "media_unavailable_reason", "transcript", "transcript_status", "transcript_parts", "variants", "variants_limited", "variants_count", "active_variants_count", "hook", "ai_tags", "cta", "landing_page_url", "overview" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/creatives/{id}/analysis": { "get": { "operationId": "getCreativeAnalysis", "summary": "Get a creative's AI analysis", "description": "The creative's record with its AI analysis: scores (an AI reading of the execution, not measured performance), objective, timed moments and the full analysis document. Needs the read permission.", "tags": [ "Creatives" ], "x-permission": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The creative id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The creative's id (its media hash)." }, "brand_key": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "brand_logo_url": { "type": [ "string", "null" ] }, "platform": { "description": "meta or google.", "type": [ "string", "null" ] }, "format": { "description": "image, video or carousel.", "type": [ "string", "null" ] }, "media_url": { "description": "The creative's media: a signed link, valid 21 days.", "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "media_urls": { "type": "array", "items": { "type": "string" } }, "external_watch_url": { "description": "A YouTube link for Google video ads, when the file is not stored.", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "first_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "last_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "status": { "description": "active, inactive or unknown.", "type": [ "string", "null" ] }, "days_active": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ads_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Source ads that run this creative." }, "tags": { "type": "array", "items": { "type": "string" } }, "language": { "type": [ "string", "null" ] }, "media_availability": { "type": [ "string", "null" ] }, "media_unavailable_reason": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] }, "transcript_status": { "type": [ "string", "null" ] }, "transcript_parts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "text": { "type": "string" } }, "required": [ "kind", "label", "text" ], "additionalProperties": false } }, "variants": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "A source ad: ad_id, source, status, activation_date, deactivation_date, title, body, related_creative_ids, source_url, placements, frames." }, "description": "The source ads that run this creative, newest first." }, "variants_limited": { "type": "boolean" }, "variants_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "active_variants_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hook": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The opening: type, description, timestamp, why." }, { "type": "null" } ] }, "ai_tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "tags": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "tag, label, value, description" } } }, "required": [ "id", "label", "tags" ], "additionalProperties": false } }, "cta": { "type": [ "string", "null" ] }, "landing_page_url": { "type": [ "string", "null" ] }, "overview": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Counted over the source ads read: ctas, landing_pages, landing_pages_total, placements, estimated_countries." }, { "type": "null" } ] }, "scores": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "out_of": { "type": [ "number", "null" ] }, "meaning": { "type": [ "string", "null" ] } }, "required": [ "id", "label", "value", "out_of", "meaning" ], "additionalProperties": false }, "description": "AI reading of the creative's execution, not measured ad performance." }, "objective": { "type": [ "string", "null" ] }, "moments": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "A timed moment of a video." } }, "analysis": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The full AI analysis document." }, { "type": "null" } ] }, "analysis_status": { "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "id", "brand_key", "brand_name", "brand_logo_url", "platform", "format", "media_url", "poster_url", "media_urls", "external_watch_url", "title", "body", "first_seen", "last_seen", "status", "days_active", "ads_count", "tags", "language", "media_availability", "media_unavailable_reason", "transcript", "transcript_status", "transcript_parts", "variants", "variants_limited", "variants_count", "active_variants_count", "hook", "ai_tags", "cta", "landing_page_url", "overview", "scores", "objective", "moments", "analysis", "analysis_status" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/creatives/{id}/similar": { "get": { "operationId": "listSimilarCreatives", "summary": "List similar creatives", "description": "Creatives of other brands that share the creative's execution and topic tags, ranked. Needs the read permission.", "tags": [ "Creatives" ], "x-permission": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The creative id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "limit", "in": "query", "required": false, "description": "Matches to return, 1 to 100 (default 20).", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "creative": { "type": "object", "properties": { "id": { "type": "string", "description": "The creative's id (its media hash)." }, "brand_key": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "brand_logo_url": { "type": [ "string", "null" ] }, "platform": { "description": "meta or google.", "type": [ "string", "null" ] }, "format": { "description": "image, video or carousel.", "type": [ "string", "null" ] }, "media_url": { "description": "The creative's media: a signed link, valid 21 days.", "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "media_urls": { "type": "array", "items": { "type": "string" } }, "external_watch_url": { "description": "A YouTube link for Google video ads, when the file is not stored.", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "first_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "last_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "status": { "description": "active, inactive or unknown.", "type": [ "string", "null" ] }, "days_active": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ads_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Source ads that run this creative." }, "tags": { "type": "array", "items": { "type": "string" } }, "language": { "type": [ "string", "null" ] }, "media_availability": { "type": [ "string", "null" ] }, "media_unavailable_reason": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] } }, "required": [ "id", "brand_key", "brand_name", "brand_logo_url", "platform", "format", "media_url", "poster_url", "media_urls", "external_watch_url", "title", "body", "first_seen", "last_seen", "status", "days_active", "ads_count", "tags", "language", "media_availability", "media_unavailable_reason", "transcript" ], "additionalProperties": false } }, "required": [ "creative" ], "additionalProperties": {} } }, "candidates_reviewed": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "candidate_limit": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "candidate_pool_limited": { "type": [ "boolean", "null" ] }, "method": { "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "candidates_reviewed", "candidate_limit", "candidate_pool_limited", "method" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/advertisers": { "get": { "operationId": "searchAdvertisers", "summary": "Search advertisers in public ad libraries", "description": "Advertisers on the Meta Ad Library or Google Ads Transparency, for a brand Adspy does not have yet. Give the chosen one's `url` to POST /v1/fetches. Needs the read permission.", "tags": [ "Fetches" ], "x-permission": "read", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "The advertiser's name.", "schema": { "type": "string", "minLength": 2, "maxLength": 160 } }, { "name": "source", "in": "query", "required": true, "description": "The public ad library to search: Meta Ad Library or Google Ads Transparency.", "schema": { "type": "string", "enum": [ "meta", "google" ] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "business_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "ad_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "country": { "type": [ "string", "null" ] }, "url": { "type": "string", "description": "Give it to POST /v1/fetches." } }, "required": [ "source", "business_id", "name", "logo_url", "ad_count", "country", "url" ], "additionalProperties": false } }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/fetches": { "post": { "operationId": "createFetch", "summary": "Collect a new brand", "description": "Asks Adspy to collect an advertiser's ads. A brand Adspy already has is returned at once (state existing), and one already being collected answers its running job: neither counts. New collections count toward the contract's monthly quota, shared with the organization's MCP connections. Follow the job with GET /v1/fetches/{id}. Needs the actions permission.", "tags": [ "Fetches" ], "x-permission": "actions", "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The advertiser's page in the Meta Ad Library (view_all_page_id) or Google Ads Transparency, from GET /v1/advertisers." }, "name": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The brand's name." }, "result_cap": { "default": 20, "description": "Suggested page size for reading the new creatives later; not an ingestion limit.", "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "url", "name" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted: the job runs in the background.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "brand_fetch", "social_fetch" ] }, "state": { "type": "string", "description": "existing (Adspy already had it: read it now), queued, pending, submitting, processing, waiting (social: retried automatically at retry_at), completed or failed." }, "is_complete": { "type": "boolean", "description": "The only signal that the collection is done; never infer it from progress." }, "is_terminal": { "type": "boolean" }, "poll_after_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "When to read the job again; null once terminal." }, "brand_key": { "type": [ "string", "null" ] }, "created_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "meta", "google" ] }, { "type": "null" } ], "description": "Brand fetches: the ad library." }, "business_id": { "description": "Brand fetches: the advertiser's id in that library.", "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "total_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "processed_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "remaining_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "result_cap": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source_coverage": { "anyOf": [ { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "expected_ads_estimate": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "observed_valid_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "low_confidence": { "type": [ "boolean", "null" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "last_scraped_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] } }, "required": [ "status", "expected_ads_estimate", "observed_valid_ads", "low_confidence", "reasons", "last_scraped_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "Brand fetches: how much of the advertiser's library was collected, when known." }, "platform": { "anyOf": [ { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, { "type": "null" } ], "description": "Social fetches." }, "account_id": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "total_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "processed_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "remaining_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "new_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "posts_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "history_complete": { "type": [ "boolean", "null" ] }, "history_days": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "retry_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "progress_percent": { "type": [ "number", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "job_id", "kind", "state", "is_complete", "is_terminal", "poll_after_seconds", "brand_key", "created_at", "updated_at", "source", "business_id", "brand_name", "total_ads", "processed_ads", "remaining_ads", "result_cap", "source_coverage", "platform", "account_id", "handle", "display_name", "url", "total_posts", "processed_posts", "remaining_posts", "new_posts", "posts_count", "history_complete", "history_days", "retry_at", "progress_percent", "error_code" ], "additionalProperties": false, "description": "A brand or social account collection." } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). idempotency_key_required: Idempotency key required (https://www.adspy.sh/docs/api/errors/idempotency-key-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "idempotency_key_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached). payment_required: Payment required (https://www.adspy.sh/docs/api/errors/payment-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached", "payment_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict: Idempotency conflict (https://www.adspy.sh/docs/api/errors/idempotency-conflict). operation_in_progress: Operation in progress (https://www.adspy.sh/docs/api/errors/operation-in-progress). conflict: Conflict (https://www.adspy.sh/docs/api/errors/conflict)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "idempotency_conflict", "operation_in_progress", "conflict" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "payload_too_large: Payload too large (https://www.adspy.sh/docs/api/errors/payload-too-large)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payload_too_large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "unsupported_media_type: Unsupported media type (https://www.adspy.sh/docs/api/errors/unsupported-media-type)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unsupported_media_type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use). fetch_quota_exceeded: Fetch quota exceeded (https://www.adspy.sh/docs/api/errors/fetch-quota-exceeded). fetch_limited: Too many fetches at once (https://www.adspy.sh/docs/api/errors/fetch-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use", "fetch_quota_exceeded", "fetch_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/fetches/{id}": { "get": { "operationId": "getFetch", "summary": "Get a fetch job", "description": "A brand or social account collection: its state and progress. A job is complete only when `is_complete` is true; then read the brand's creatives (GET /v1/brands/{brand_key}/creatives) or the account's posts (GET /v1/social/posts). Needs the actions permission.", "tags": [ "Fetches" ], "x-permission": "actions", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The fetch job id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "brand_fetch", "social_fetch" ] }, "state": { "type": "string", "description": "existing (Adspy already had it: read it now), queued, pending, submitting, processing, waiting (social: retried automatically at retry_at), completed or failed." }, "is_complete": { "type": "boolean", "description": "The only signal that the collection is done; never infer it from progress." }, "is_terminal": { "type": "boolean" }, "poll_after_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "When to read the job again; null once terminal." }, "brand_key": { "type": [ "string", "null" ] }, "created_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "meta", "google" ] }, { "type": "null" } ], "description": "Brand fetches: the ad library." }, "business_id": { "description": "Brand fetches: the advertiser's id in that library.", "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "total_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "processed_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "remaining_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "result_cap": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source_coverage": { "anyOf": [ { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "expected_ads_estimate": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "observed_valid_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "low_confidence": { "type": [ "boolean", "null" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "last_scraped_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] } }, "required": [ "status", "expected_ads_estimate", "observed_valid_ads", "low_confidence", "reasons", "last_scraped_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "Brand fetches: how much of the advertiser's library was collected, when known." }, "platform": { "anyOf": [ { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, { "type": "null" } ], "description": "Social fetches." }, "account_id": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "total_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "processed_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "remaining_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "new_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "posts_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "history_complete": { "type": [ "boolean", "null" ] }, "history_days": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "retry_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "progress_percent": { "type": [ "number", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "job_id", "kind", "state", "is_complete", "is_terminal", "poll_after_seconds", "brand_key", "created_at", "updated_at", "source", "business_id", "brand_name", "total_ads", "processed_ads", "remaining_ads", "result_cap", "source_coverage", "platform", "account_id", "handle", "display_name", "url", "total_posts", "processed_posts", "remaining_posts", "new_posts", "posts_count", "history_complete", "history_days", "retry_at", "progress_percent", "error_code" ], "additionalProperties": false, "description": "A brand or social account collection." } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/social/accounts": { "get": { "operationId": "searchSocialAccounts", "summary": "Search social accounts", "description": "TikTok or YouTube accounts for a brand or a handle: the ones Adspy collects, then the platform's own search. `official` is true only with proof that the account is the brand's. Needs the read permission.", "tags": [ "Social" ], "x-permission": "read", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "A brand name or a handle.", "schema": { "type": "string", "minLength": 2, "maxLength": 80 } }, { "name": "platform", "in": "query", "required": true, "description": "tiktok or youtube. Instagram is not available in the API.", "schema": { "type": "string", "enum": [ "tiktok", "youtube" ] } }, { "name": "brand_key", "in": "query", "required": false, "description": "The Adspy brand, when known: its linked accounts and website are used as proof.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "handle": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "verified": { "type": [ "boolean", "null" ] }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "official": { "description": "True only with proof that the account is the brand's.", "type": [ "boolean", "null" ] }, "label": { "type": [ "string", "null" ] }, "tracked": { "description": "Adspy already collects it: reading it is free.", "type": [ "boolean", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "brand_key": { "type": [ "string", "null" ] } }, "required": [ "platform", "handle", "url", "display_name", "verified", "followers", "official", "label", "tracked", "account_id", "brand_key" ], "additionalProperties": {} } }, "status": { "description": "found, not_found, search_unavailable, …", "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "retry_after_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "status", "reason", "retry_after_seconds" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "instagram_not_in_api: Instagram is not available in the API (https://www.adspy.sh/docs/api/errors/instagram-not-in-api)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "instagram_not_in_api" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/social/fetches": { "post": { "operationId": "createSocialFetch", "summary": "Collect a social account", "description": "Asks Adspy to collect a TikTok or YouTube account's posts. An account Adspy already collects is returned at once (state existing), and one already being collected answers its running job: neither counts. New collections count toward the contract's monthly quota, shared with the organization's MCP connections. Follow the job with GET /v1/fetches/{id}. Needs the actions permission.", "tags": [ "Social" ], "x-permission": "actions", "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "url": { "description": "The profile link, e.g. https://www.tiktok.com/@handle. Give url or handle.", "type": "string", "minLength": 1, "maxLength": 2048 }, "handle": { "description": "The @handle.", "type": "string", "minLength": 1, "maxLength": 64 }, "brand_key": { "description": "The brand the account belongs to: it is linked on proof only.", "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, "required": [ "platform" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted: the job runs in the background.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "brand_fetch", "social_fetch" ] }, "state": { "type": "string", "description": "existing (Adspy already had it: read it now), queued, pending, submitting, processing, waiting (social: retried automatically at retry_at), completed or failed." }, "is_complete": { "type": "boolean", "description": "The only signal that the collection is done; never infer it from progress." }, "is_terminal": { "type": "boolean" }, "poll_after_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "When to read the job again; null once terminal." }, "brand_key": { "type": [ "string", "null" ] }, "created_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "meta", "google" ] }, { "type": "null" } ], "description": "Brand fetches: the ad library." }, "business_id": { "description": "Brand fetches: the advertiser's id in that library.", "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "total_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "processed_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "remaining_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "result_cap": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source_coverage": { "anyOf": [ { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "expected_ads_estimate": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "observed_valid_ads": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "low_confidence": { "type": [ "boolean", "null" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "last_scraped_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] } }, "required": [ "status", "expected_ads_estimate", "observed_valid_ads", "low_confidence", "reasons", "last_scraped_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "Brand fetches: how much of the advertiser's library was collected, when known." }, "platform": { "anyOf": [ { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, { "type": "null" } ], "description": "Social fetches." }, "account_id": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "total_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "processed_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "remaining_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "new_posts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "posts_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "history_complete": { "type": [ "boolean", "null" ] }, "history_days": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "retry_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "progress_percent": { "type": [ "number", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "job_id", "kind", "state", "is_complete", "is_terminal", "poll_after_seconds", "brand_key", "created_at", "updated_at", "source", "business_id", "brand_name", "total_ads", "processed_ads", "remaining_ads", "result_cap", "source_coverage", "platform", "account_id", "handle", "display_name", "url", "total_posts", "processed_posts", "remaining_posts", "new_posts", "posts_count", "history_complete", "history_days", "retry_at", "progress_percent", "error_code" ], "additionalProperties": false, "description": "A brand or social account collection." } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). idempotency_key_required: Idempotency key required (https://www.adspy.sh/docs/api/errors/idempotency-key-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "idempotency_key_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached). payment_required: Payment required (https://www.adspy.sh/docs/api/errors/payment-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached", "payment_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict: Idempotency conflict (https://www.adspy.sh/docs/api/errors/idempotency-conflict). operation_in_progress: Operation in progress (https://www.adspy.sh/docs/api/errors/operation-in-progress)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "idempotency_conflict", "operation_in_progress" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "payload_too_large: Payload too large (https://www.adspy.sh/docs/api/errors/payload-too-large)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payload_too_large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "unsupported_media_type: Unsupported media type (https://www.adspy.sh/docs/api/errors/unsupported-media-type)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unsupported_media_type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "instagram_not_in_api: Instagram is not available in the API (https://www.adspy.sh/docs/api/errors/instagram-not-in-api)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "instagram_not_in_api" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use). fetch_quota_exceeded: Fetch quota exceeded (https://www.adspy.sh/docs/api/errors/fetch-quota-exceeded). fetch_limited: Too many fetches at once (https://www.adspy.sh/docs/api/errors/fetch-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use", "fetch_quota_exceeded", "fetch_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/social/posts": { "get": { "operationId": "listSocialPosts", "summary": "List social posts", "description": "A brand's (or one account's) organic TikTok and YouTube posts with their public counts. Instagram posts are left out, so a page can hold fewer posts than `limit`: follow `has_more`. Needs the read permission.", "tags": [ "Social" ], "x-permission": "read", "parameters": [ { "name": "brand_key", "in": "query", "required": false, "description": "The brand; give brand_key or account_id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "account_id", "in": "query", "required": false, "description": "An account id, e.g. social:tiktok:6643891469239320582.", "schema": { "type": "string", "pattern": "^social:(tiktok|youtube):[A-Za-z0-9_.-]{1,128}$" } }, { "name": "platform", "in": "query", "required": false, "description": "tiktok or youtube. Instagram is not available in the API.", "schema": { "type": "string", "enum": [ "tiktok", "youtube" ] } }, { "name": "format", "in": "query", "required": false, "description": "TikTok: video, carousel (photo post), live. YouTube: video, short, live.", "schema": { "type": "string", "enum": [ "video", "short", "live", "carousel", "image" ] } }, { "name": "since", "in": "query", "required": false, "description": "Posts published on or after this date (YYYY-MM-DD).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "sort", "in": "query", "required": false, "description": "recent: newest first. engagement: highest engagement per view first. breakouts: the posts far above the account's usual views (90-day statistics).", "schema": { "default": "recent", "type": "string", "enum": [ "recent", "engagement", "breakouts" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100 (default 20).", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Send it with the same filters; it is valid for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 600 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "post_id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "brand_key": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "published_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "published_at_approx": { "type": [ "boolean", "null" ] }, "format": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "duration_sec": { "type": [ "number", "null" ] }, "thumb_url": { "type": [ "string", "null" ] }, "counts": { "type": "object", "properties": { "views": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "comments": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "shares": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "saves": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "views", "likes", "comments", "shares", "saves" ], "additionalProperties": false, "description": "Public counts; null when the platform does not show one (never zero)." }, "counts_rounded": { "type": [ "boolean", "null" ] }, "counts_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "engagement_rate": { "description": "Engagement per view (posts with 50+ views).", "type": [ "number", "null" ] }, "reach": { "description": "breakout, paid_reach or null (90-day statistics).", "type": [ "string", "null" ] }, "ran_as_ad": { "type": [ "boolean", "null" ] }, "promoted_flag": { "type": [ "boolean", "null" ] }, "pinned": { "type": [ "boolean", "null" ] }, "deleted_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] } }, "required": [ "id", "platform", "post_id", "account_id", "handle", "brand_key", "permalink", "published_at", "published_at_approx", "format", "title", "caption", "hashtags", "duration_sec", "thumb_url", "counts", "counts_rounded", "counts_at", "engagement_rate", "reach", "ran_as_ad", "promoted_flag", "pinned", "deleted_at" ], "additionalProperties": {} } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Send it as `cursor`, with the same filters, for the next page.", "type": [ "string", "null" ] }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "handle": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "profile_url": { "type": [ "string", "null" ] }, "verified": { "type": [ "boolean", "null" ] }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "followers_rounded": { "type": [ "boolean", "null" ] }, "posts_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "history_complete": { "type": [ "boolean", "null" ] }, "last_success_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "status": { "type": [ "string", "null" ] } }, "required": [ "account_id", "platform", "handle", "display_name", "profile_url", "verified", "followers", "followers_rounded", "posts_count", "history_complete", "last_success_at", "status" ], "additionalProperties": false } }, "reach_labels": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "analysis": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "has_more", "next_cursor", "accounts", "reach_labels", "analysis" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). invalid_cursor: Invalid cursor (https://www.adspy.sh/docs/api/errors/invalid-cursor)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "invalid_cursor" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "instagram_not_in_api: Instagram is not available in the API (https://www.adspy.sh/docs/api/errors/instagram-not-in-api)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "instagram_not_in_api" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/social/posts/{id}": { "get": { "operationId": "getSocialPost", "summary": "Get a social post", "description": "One TikTok or YouTube post with its count snapshots, ad links, pre-ad counts and, on request, its AI tags. Needs the read permission.", "tags": [ "Social" ], "x-permission": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A post id, platform:native id, e.g. tiktok:7675005480867073311.", "schema": { "type": "string", "pattern": "^(tiktok|youtube):[A-Za-z0-9_-]{1,64}$" } }, { "name": "include_analysis", "in": "query", "required": false, "description": "true adds the post's AI tags (default false).", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "post_id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "brand_key": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "published_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "published_at_approx": { "type": [ "boolean", "null" ] }, "format": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "duration_sec": { "type": [ "number", "null" ] }, "thumb_url": { "type": [ "string", "null" ] }, "counts": { "type": "object", "properties": { "views": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "comments": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "shares": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "saves": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "views", "likes", "comments", "shares", "saves" ], "additionalProperties": false, "description": "Public counts; null when the platform does not show one (never zero)." }, "counts_rounded": { "type": [ "boolean", "null" ] }, "counts_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "engagement_rate": { "description": "Engagement per view (posts with 50+ views).", "type": [ "number", "null" ] }, "reach": { "description": "breakout, paid_reach or null (90-day statistics).", "type": [ "string", "null" ] }, "ran_as_ad": { "type": [ "boolean", "null" ] }, "promoted_flag": { "type": [ "boolean", "null" ] }, "pinned": { "type": [ "boolean", "null" ] }, "deleted_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "id", "platform", "post_id", "account_id", "handle", "brand_key", "permalink", "published_at", "published_at_approx", "format", "title", "caption", "hashtags", "duration_sec", "thumb_url", "counts", "counts_rounded", "counts_at", "engagement_rate", "reach", "ran_as_ad", "promoted_flag", "pinned", "deleted_at" ], "additionalProperties": {} } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "instagram_not_in_api: Instagram is not available in the API (https://www.adspy.sh/docs/api/errors/instagram-not-in-api)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "instagram_not_in_api" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/compare/brands": { "post": { "operationId": "compareBrands", "summary": "Compare brands", "description": "The X-Rays of 2 to 5 brands over one range, side by side. Each brand's report is reused for 24 hours. Needs the actions permission.", "tags": [ "Reports" ], "x-permission": "actions", "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brand_keys": { "minItems": 2, "maxItems": 5, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" }, "description": "2 to 5 brand keys." }, "range": { "default": "90d", "description": "The window of first sightings the report covers (default 90d).", "type": "string", "enum": [ "30d", "90d", "180d", "all" ] } }, "required": [ "brand_keys" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "reports": { "type": "array", "items": { "type": "object", "properties": { "instagram_excluded": { "type": "boolean" } }, "additionalProperties": {}, "description": "One brand's X-Ray." } }, "missing": { "type": "array", "items": { "type": "object", "properties": { "brand_key": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "brand_key", "reason" ], "additionalProperties": false } }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "reports", "missing", "billing" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). idempotency_key_required: Idempotency key required (https://www.adspy.sh/docs/api/errors/idempotency-key-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "idempotency_key_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached). payment_required: Payment required (https://www.adspy.sh/docs/api/errors/payment-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached", "payment_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict: Idempotency conflict (https://www.adspy.sh/docs/api/errors/idempotency-conflict). operation_in_progress: Operation in progress (https://www.adspy.sh/docs/api/errors/operation-in-progress)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "idempotency_conflict", "operation_in_progress" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "payload_too_large: Payload too large (https://www.adspy.sh/docs/api/errors/payload-too-large)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payload_too_large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "unsupported_media_type: Unsupported media type (https://www.adspy.sh/docs/api/errors/unsupported-media-type)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unsupported_media_type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "timeout: Timeout (https://www.adspy.sh/docs/api/errors/timeout)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "timeout" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/compare/social": { "post": { "operationId": "compareSocial", "summary": "Compare brands on TikTok or YouTube", "description": "2 to 5 brands' organic posts on one platform: engagement per view and views per post, each brand's median against its peers with a stratified bootstrap, cadence, breakouts and paid reach. Needs the actions permission.", "tags": [ "Reports" ], "x-permission": "actions", "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brand_keys": { "minItems": 2, "maxItems": 5, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" }, "description": "2 to 5 brand keys." }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "range": { "default": "90d", "description": "The statistics window: the last 30 or 90 days (default 90d).", "type": "string", "enum": [ "30d", "90d" ] } }, "required": [ "brand_keys", "platform" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "instagram_excluded": { "type": "boolean" }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "additionalProperties": {}, "description": "The comparison." } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). idempotency_key_required: Idempotency key required (https://www.adspy.sh/docs/api/errors/idempotency-key-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "idempotency_key_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached). payment_required: Payment required (https://www.adspy.sh/docs/api/errors/payment-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached", "payment_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict: Idempotency conflict (https://www.adspy.sh/docs/api/errors/idempotency-conflict). operation_in_progress: Operation in progress (https://www.adspy.sh/docs/api/errors/operation-in-progress)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "idempotency_conflict", "operation_in_progress" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "payload_too_large: Payload too large (https://www.adspy.sh/docs/api/errors/payload-too-large)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payload_too_large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "unsupported_media_type: Unsupported media type (https://www.adspy.sh/docs/api/errors/unsupported-media-type)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unsupported_media_type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "instagram_not_in_api: Instagram is not available in the API (https://www.adspy.sh/docs/api/errors/instagram-not-in-api)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "instagram_not_in_api" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/collections": { "get": { "operationId": "listCollections", "summary": "List collections", "description": "The workspace's collections of saved creatives, 100 per page. Needs the read permission.", "tags": [ "Collections" ], "x-permission": "read", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Send it with the same filters; it is valid for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 600 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "name", "description", "count" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Send it as `cursor`, with the same filters, for the next page.", "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). invalid_cursor: Invalid cursor (https://www.adspy.sh/docs/api/errors/invalid-cursor)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "invalid_cursor" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createCollection", "summary": "Save creatives to a new collection", "description": "Creates a collection with these creatives, or adds them to your collection that already has this name. Creatives the library does not hold are left out and listed in `not_saved`; when none is held, nothing is created (404). Needs the actions permission.", "tags": [ "Collections" ], "x-permission": "actions", "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The collection's name. An existing collection of yours with this name is reused." }, "creative_ids": { "description": "1 to 100 creative ids.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } }, "required": [ "name", "creative_ids" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_id": { "type": "string" }, "updated": { "type": "boolean" }, "not_saved": { "description": "Creative ids the library does not hold, left out of the save.", "type": "array", "items": { "type": "string" } }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "collection_id", "updated" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). idempotency_key_required: Idempotency key required (https://www.adspy.sh/docs/api/errors/idempotency-key-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "idempotency_key_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict: Idempotency conflict (https://www.adspy.sh/docs/api/errors/idempotency-conflict). operation_in_progress: Operation in progress (https://www.adspy.sh/docs/api/errors/operation-in-progress)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "idempotency_conflict", "operation_in_progress" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "payload_too_large: Payload too large (https://www.adspy.sh/docs/api/errors/payload-too-large)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payload_too_large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "unsupported_media_type: Unsupported media type (https://www.adspy.sh/docs/api/errors/unsupported-media-type)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unsupported_media_type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/collections/{id}": { "get": { "operationId": "getCollection", "summary": "Get a collection", "description": "A collection and its creatives with their notes. `expand=true` adds each creative's record. Needs the read permission.", "tags": [ "Collections" ], "x-permission": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The collection id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "expand", "in": "query", "required": false, "description": "true adds each creative's record (default false).", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100 (default 20).", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Send it with the same filters; it is valid for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 600 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "creative_id": { "type": "string" }, "note": { "type": "string" }, "added_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "creative": { "type": "object", "properties": { "id": { "type": "string", "description": "The creative's id (its media hash)." }, "brand_key": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "brand_logo_url": { "type": [ "string", "null" ] }, "platform": { "description": "meta or google.", "type": [ "string", "null" ] }, "format": { "description": "image, video or carousel.", "type": [ "string", "null" ] }, "media_url": { "description": "The creative's media: a signed link, valid 21 days.", "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "media_urls": { "type": "array", "items": { "type": "string" } }, "external_watch_url": { "description": "A YouTube link for Google video ads, when the file is not stored.", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "first_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "last_seen": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "status": { "description": "active, inactive or unknown.", "type": [ "string", "null" ] }, "days_active": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ads_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Source ads that run this creative." }, "tags": { "type": "array", "items": { "type": "string" } }, "language": { "type": [ "string", "null" ] }, "media_availability": { "type": [ "string", "null" ] }, "media_unavailable_reason": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] }, "transcript_status": { "type": [ "string", "null" ] }, "transcript_parts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "text": { "type": "string" } }, "required": [ "kind", "label", "text" ], "additionalProperties": false } }, "variants": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "A source ad: ad_id, source, status, activation_date, deactivation_date, title, body, related_creative_ids, source_url, placements, frames." }, "description": "The source ads that run this creative, newest first." }, "variants_limited": { "type": "boolean" }, "variants_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "active_variants_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hook": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The opening: type, description, timestamp, why." }, { "type": "null" } ] }, "ai_tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "tags": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "tag, label, value, description" } } }, "required": [ "id", "label", "tags" ], "additionalProperties": false } }, "cta": { "type": [ "string", "null" ] }, "landing_page_url": { "type": [ "string", "null" ] }, "overview": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Counted over the source ads read: ctas, landing_pages, landing_pages_total, placements, estimated_countries." }, { "type": "null" } ] } }, "required": [ "id", "brand_key", "brand_name", "brand_logo_url", "platform", "format", "media_url", "poster_url", "media_urls", "external_watch_url", "title", "body", "first_seen", "last_seen", "status", "days_active", "ads_count", "tags", "language", "media_availability", "media_unavailable_reason", "transcript", "transcript_status", "transcript_parts", "variants", "variants_limited", "variants_count", "active_variants_count", "hook", "ai_tags", "cta", "landing_page_url", "overview" ], "additionalProperties": false } }, "required": [ "creative_id", "note", "added_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Send it as `cursor`, with the same filters, for the next page.", "type": [ "string", "null" ] }, "collection": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "color" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "has_more", "next_cursor", "collection" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). invalid_cursor: Invalid cursor (https://www.adspy.sh/docs/api/errors/invalid-cursor)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "invalid_cursor" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "partner_key_cap_reached: Partner key cap reached (https://www.adspy.sh/docs/api/errors/partner-key-cap-reached). partner_tenant_cap_reached: Partner tenant cap reached (https://www.adspy.sh/docs/api/errors/partner-tenant-cap-reached)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "partner_key_cap_reached", "partner_tenant_cap_reached" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited). partner_fair_use: Partner fair use (https://www.adspy.sh/docs/api/errors/partner-fair-use)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited", "partner_fair_use" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/collections/{id}/creatives": { "post": { "operationId": "addCollectionCreatives", "summary": "Add creatives to a collection", "description": "Adds creatives to the collection. A creative already in it keeps its note. Creatives the library does not hold are left out and listed in `not_saved`; when none is held, nothing is added (404). Needs the actions permission.", "tags": [ "Collections" ], "x-permission": "actions", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The collection id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creative_ids": { "description": "1 to 100 creative ids.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } }, "required": [ "creative_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_id": { "type": "string" }, "updated": { "type": "boolean" }, "not_saved": { "description": "Creative ids the library does not hold, left out of the save.", "type": "array", "items": { "type": "string" } }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "collection_id", "updated" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). idempotency_key_required: Idempotency key required (https://www.adspy.sh/docs/api/errors/idempotency-key-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "idempotency_key_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict: Idempotency conflict (https://www.adspy.sh/docs/api/errors/idempotency-conflict). operation_in_progress: Operation in progress (https://www.adspy.sh/docs/api/errors/operation-in-progress)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "idempotency_conflict", "operation_in_progress" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "payload_too_large: Payload too large (https://www.adspy.sh/docs/api/errors/payload-too-large)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payload_too_large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "unsupported_media_type: Unsupported media type (https://www.adspy.sh/docs/api/errors/unsupported-media-type)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unsupported_media_type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/collections/{id}/creatives/{creative_id}": { "patch": { "operationId": "updateCollectionNote", "summary": "Set a creative's note", "description": "Sets the note of a creative in the collection. Sending the same note again changes nothing. Needs the actions permission.", "tags": [ "Collections" ], "x-permission": "actions", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The collection id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, { "name": "creative_id", "in": "path", "required": true, "description": "The creative id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 10000, "description": "The note; an empty string clears it." } }, "required": [ "note" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_id": { "type": "string" }, "creative_id": { "type": "string" }, "note": { "type": "string" }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "collection_id", "creative_id", "note" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "payload_too_large: Payload too large (https://www.adspy.sh/docs/api/errors/payload-too-large)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payload_too_large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "unsupported_media_type: Unsupported media type (https://www.adspy.sh/docs/api/errors/unsupported-media-type)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unsupported_media_type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/exports": { "post": { "operationId": "createExport", "summary": "Create an export", "description": "Exports up to 10,000 items as CSV, Excel, JSON, ZIP (with media), PDF, Markdown or HTML. The file is built in the background: follow the job with GET /v1/exports/{id}. Files are kept 7 days. Social exports take platform tiktok or youtube. Needs the export permission.", "tags": [ "Exports" ], "x-permission": "export", "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "creatives" }, "filters": { "type": "object", "properties": { "query": { "description": "Words to find, in the scope chosen.", "type": "string", "maxLength": 160 }, "scope": { "default": "all", "description": "Where `query` is matched (default all).", "type": "string", "enum": [ "all", "ad_copy", "content_transcript", "visual_analysis", "all_keywords", "hooks" ] }, "platform": { "description": "The ad library: meta (Facebook, Instagram and Messenger placements) or google (Search, YouTube, Display).", "type": "string", "enum": [ "all", "meta", "google" ] }, "format": { "type": "string", "enum": [ "all", "image", "video", "carousel" ] }, "status": { "description": "Whether the library last saw the ad running.", "type": "string", "enum": [ "all", "active", "inactive" ] }, "sort": { "default": "newest", "description": "newest or oldest first sighting, or longest running (default newest).", "type": "string", "enum": [ "newest", "oldest", "longest" ] }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "language": { "type": "string", "maxLength": 30 }, "min_days_active": { "description": "Only creatives seen running for at least this many days.", "type": "integer", "minimum": 0, "maximum": 36500 }, "brand_key": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" }, "brand_keys": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } }, "additionalProperties": false } }, "required": [ "kind", "filters" ], "additionalProperties": false, "description": "Every creative matching search filters." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "creative_ids" }, "creative_ids": { "minItems": 1, "maxItems": 10000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } }, "required": [ "kind", "creative_ids" ], "additionalProperties": false, "description": "Given creatives, up to 10,000." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "collection" }, "collection_id": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, "required": [ "kind", "collection_id" ], "additionalProperties": false, "description": "A collection's creatives." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "social_posts" }, "filters": { "type": "object", "properties": { "brand_key": { "description": "The brand; give brand_key or account_id.", "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" }, "account_id": { "type": "string", "pattern": "^social:(tiktok|youtube):[A-Za-z0-9_.-]{1,128}$", "description": "An account id, e.g. social:tiktok:6643891469239320582." }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "format": { "description": "TikTok: video, carousel (photo post), live. YouTube: video, short, live.", "type": "string", "enum": [ "video", "short", "live", "carousel", "image" ] }, "since": { "description": "Posts published on or after this date (YYYY-MM-DD).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "sort": { "default": "recent", "description": "recent: newest first. engagement: highest engagement per view first. breakouts: the posts far above the account's usual views (90-day statistics).", "type": "string", "enum": [ "recent", "engagement", "breakouts" ] } }, "required": [ "platform" ], "additionalProperties": false } }, "required": [ "kind", "filters" ], "additionalProperties": false, "description": "Posts matching filters, on one platform." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "post_ad_pairs" }, "filters": { "type": "object", "properties": { "brand_key": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" }, "range": { "default": "90d", "description": "Posts published in this window (default 90d).", "type": "string", "enum": [ "30d", "90d", "180d", "all" ] }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "direction": { "default": "organic_to_paid", "description": "organic_to_paid: posts later run as ads. paid_to_organic: ads later posted organically.", "type": "string", "enum": [ "organic_to_paid", "paid_to_organic", "all" ] } }, "required": [ "brand_key", "platform" ], "additionalProperties": false } }, "required": [ "kind", "filters" ], "additionalProperties": false, "description": "A brand's posts run as ads, on one platform." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "social_comparison" }, "brand_keys": { "minItems": 2, "maxItems": 5, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ], "description": "tiktok or youtube. Instagram is not available in the API." }, "range": { "default": "90d", "description": "The statistics window: the last 30 or 90 days (default 90d).", "type": "string", "enum": [ "30d", "90d" ] } }, "required": [ "kind", "brand_keys", "platform" ], "additionalProperties": false, "description": "A social comparison of 2 to 5 brands." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "brand_xray" }, "brand_keys": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } }, "range": { "default": "90d", "description": "The window of first sightings the report covers (default 90d).", "type": "string", "enum": [ "30d", "90d", "180d", "all" ] } }, "required": [ "kind", "brand_keys" ], "additionalProperties": false, "description": "Brand X-Rays of 1 to 20 brands." } ] }, "format": { "type": "string", "enum": [ "csv", "xlsx", "json", "zip", "pdf", "markdown", "html" ], "description": "csv: one table. xlsx: sheets with an About sheet. json: everything with a manifest. zip: CSV + JSON + media files. pdf: reports, X-Rays and comparisons. markdown and html: creatives only." }, "include": { "type": "object", "properties": { "analysis": { "default": false, "description": "Add analyses or AI tags.", "type": "boolean" }, "transcripts": { "description": "Add creative transcripts.", "type": "boolean" }, "media": { "description": "zip only: thumbnails (default, up to 2,000 files) or originals (up to 200 files and 2 GB).", "type": "string", "enum": [ "none", "thumbnails", "originals" ] } }, "additionalProperties": false } }, "required": [ "source", "format" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted: the job runs in the background.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "running", "partial", "completed", "failed" ] }, "title": { "description": "A short name of what is exported, such as \"120 ads of Northstar\".", "type": [ "string", "null" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": {} }, { "type": "null" } ], "description": "What is exported: its kind (creatives, creative_ids, collection, social_posts, post_ad_pairs, social_comparison, brand_xray) and size." }, "format": { "type": [ "string", "null" ] }, "completed_items": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "requested_items": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "missing_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "filename": { "type": [ "string", "null" ] }, "created_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "error_code": { "type": [ "string", "null" ] }, "download_url": { "description": "A link valid 5 minutes, when the file is ready. Read the job again for a new one.", "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "job_id", "state", "title", "source", "format", "completed_items", "requested_items", "missing_count", "bytes", "filename", "created_at", "expires_at", "error_code", "download_url" ], "additionalProperties": {} } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). idempotency_key_required: Idempotency key required (https://www.adspy.sh/docs/api/errors/idempotency-key-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "idempotency_key_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "payment_required: Payment required (https://www.adspy.sh/docs/api/errors/payment-required)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payment_required" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden). not_offered_to_partner: Not offered to partner keys (https://www.adspy.sh/docs/api/errors/not-offered-to-partner)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden", "not_offered_to_partner" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "idempotency_conflict: Idempotency conflict (https://www.adspy.sh/docs/api/errors/idempotency-conflict). operation_in_progress: Operation in progress (https://www.adspy.sh/docs/api/errors/operation-in-progress)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "idempotency_conflict", "operation_in_progress" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "payload_too_large: Payload too large (https://www.adspy.sh/docs/api/errors/payload-too-large)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "payload_too_large" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "unsupported_media_type: Unsupported media type (https://www.adspy.sh/docs/api/errors/unsupported-media-type)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unsupported_media_type" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "instagram_not_in_api: Instagram is not available in the API (https://www.adspy.sh/docs/api/errors/instagram-not-in-api)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "instagram_not_in_api" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "listExports", "summary": "List exports", "description": "The exports the key's user made in its workspace in the last 7 days, newest first, through the API or in Adspy. Exports of a source the API does not offer (Instagram among them) are left out, so a page can hold fewer than `limit`: follow `has_more`. Needs the export permission.", "tags": [ "Exports" ], "x-permission": "export", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "running", "completed", "partial", "failed" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 50 (default 20).", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page. Send it with the same filters; it is valid for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 600 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "job_id": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "running", "partial", "completed", "failed" ] }, "title": { "description": "A short name of what is exported, such as \"120 ads of Northstar\".", "type": [ "string", "null" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": {} }, { "type": "null" } ], "description": "What is exported: its kind (creatives, creative_ids, collection, social_posts, post_ad_pairs, social_comparison, brand_xray) and size." }, "format": { "type": [ "string", "null" ] }, "completed_items": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "requested_items": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "missing_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "filename": { "type": [ "string", "null" ] }, "created_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "error_code": { "type": [ "string", "null" ] }, "download_url": { "description": "A link valid 5 minutes, when the file is ready. Read the job again for a new one.", "type": [ "string", "null" ] } }, "required": [ "job_id", "state", "title", "source", "format", "completed_items", "requested_items", "missing_count", "bytes", "filename", "created_at", "expires_at", "error_code", "download_url" ], "additionalProperties": {} } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Send it as `cursor`, with the same filters, for the next page.", "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request). invalid_cursor: Invalid cursor (https://www.adspy.sh/docs/api/errors/invalid-cursor)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request", "invalid_cursor" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden). not_offered_to_partner: Not offered to partner keys (https://www.adspy.sh/docs/api/errors/not-offered-to-partner)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden", "not_offered_to_partner" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/exports/{id}": { "get": { "operationId": "getExport", "summary": "Get an export", "description": "An export job and, when the file is ready, a download link valid 5 minutes. An export of a source the API does not offer, made in Adspy, is not available here. Needs the export permission.", "tags": [ "Exports" ], "x-permission": "export", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The export job id.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\s\\x00-\\x1f]+$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "running", "partial", "completed", "failed" ] }, "title": { "description": "A short name of what is exported, such as \"120 ads of Northstar\".", "type": [ "string", "null" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": {} }, { "type": "null" } ], "description": "What is exported: its kind (creatives, creative_ids, collection, social_posts, post_ad_pairs, social_comparison, brand_xray) and size." }, "format": { "type": [ "string", "null" ] }, "completed_items": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "requested_items": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "missing_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "filename": { "type": [ "string", "null" ] }, "created_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] }, "error_code": { "type": [ "string", "null" ] }, "download_url": { "description": "A link valid 5 minutes, when the file is ready. Read the job again for a new one.", "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "job_id", "state", "title", "source", "format", "completed_items", "requested_items", "missing_count", "bytes", "filename", "created_at", "expires_at", "error_code", "download_url" ], "additionalProperties": {} } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden). not_offered_to_partner: Not offered to partner keys (https://www.adspy.sh/docs/api/errors/not-offered-to-partner)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden", "not_offered_to_partner" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: Not found (https://www.adspy.sh/docs/api/errors/not-found)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "not_found" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "instagram_not_in_api: Instagram is not available in the API (https://www.adspy.sh/docs/api/errors/instagram-not-in-api)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "instagram_not_in_api" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "Get usage", "description": "The organization's plan, the contract's limits, this month's new collections and the operations of the last 30 days. Enterprise has no credit count: its credit fields are null or 0. Needs the read permission.", "tags": [ "Usage" ], "x-permission": "read", "parameters": [], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "description": "The organization's plan: Enterprise.", "type": [ "string", "null" ] }, "unlimited": { "type": "boolean", "description": "True on Enterprise: there is no credit count." }, "credits": { "type": "object", "properties": { "available": { "type": [ "number", "null" ] }, "used_this_month": { "type": [ "number", "null" ] }, "renews_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 date and time, UTC." }, { "type": "null" } ] } }, "required": [ "available", "used_this_month", "renews_at" ], "additionalProperties": false, "description": "Its fields are null on Enterprise, which has no credit count." }, "limits": { "type": "object", "properties": { "requests_per_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Requests a minute for this key, set by the contract." }, "fetches_per_month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "New brand or account collections a month for the organization, set by the contract." }, "fetches_this_month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "New collections the organization started this month (UTC), from its API keys and its MCP connections: the count fetch_quota_exceeded checks." } }, "required": [ "requests_per_minute", "fetches_per_month", "fetches_this_month" ], "additionalProperties": false }, "spent": { "type": "object", "properties": { "days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "by_operation": { "type": "array", "items": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "full_analysis", "xray", "social_report", "brand_comparison", "social_comparison", "brand_fetch", "social_fetch", "export", "other" ], "description": "The charged operation." }, "credits": { "type": "number", "description": "0 on Enterprise." }, "operations": { "type": "number" } }, "required": [ "operation", "credits", "operations" ], "additionalProperties": false } } }, "required": [ "days", "by_operation" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." } }, "required": [ "plan", "unlimited", "credits", "limits", "spent" ], "additionalProperties": false } } } }, "400": { "description": "invalid_request: Invalid request (https://www.adspy.sh/docs/api/errors/invalid-request)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "invalid_request" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: Unauthorized (https://www.adspy.sh/docs/api/errors/unauthorized)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "unauthorized" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "enterprise_required: Enterprise required (https://www.adspy.sh/docs/api/errors/enterprise-required). insufficient_scope: Insufficient scope (https://www.adspy.sh/docs/api/errors/insufficient-scope). forbidden: Forbidden (https://www.adspy.sh/docs/api/errors/forbidden). not_offered_to_partner: Not offered to partner keys (https://www.adspy.sh/docs/api/errors/not-offered-to-partner)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "enterprise_required", "insufficient_scope", "forbidden", "not_offered_to_partner" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: Rate limited (https://www.adspy.sh/docs/api/errors/rate-limited)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "rate_limited" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "internal_error: Internal error (https://www.adspy.sh/docs/api/errors/internal-error)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "x-error-codes": [ "internal_error" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "service_unavailable: Service unavailable (https://www.adspy.sh/docs/api/errors/service-unavailable)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "x-error-codes": [ "service_unavailable" ], "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An Adspy API key, created by an organization owner or admin in the Adspy console: `Authorization: Bearer `." }, "partnerKey": { "type": "http", "scheme": "bearer", "description": "A partner key (adspy_partner_), issued by Adspy to a partner product: `Authorization: Bearer `. A key pinned to one tenant acts for it alone; any other names its tenant in the X-Agentik-Tenant header. Every partner answer carries `billing`, the key's monthly cap applies (partner_key_cap_reached), and exports and usage are not offered (not_offered_to_partner). See https://www.adspy.sh/docs/api/partner-keys." } }, "schemas": { "Billing": { "type": "object", "properties": { "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this request charged: always 0 on Enterprise, which has no credit count. On a partner key, the credits the partner bills: each new item read, and reports and new collections at their price." }, "usd_micros": { "description": "Partner keys only: what the partner bills, in micro-dollars.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "operation_id": { "description": "Partner keys only: the settled operation, for reconciliation; null when nothing was settled.", "type": [ "string", "null" ] }, "replayed": { "description": "Partner keys only: true when the answer replays an earlier request, billed then.", "type": "boolean" }, "price_version": { "description": "Partner keys only: the version of the partner prices applied.", "type": "string" } }, "required": [ "credits_charged" ], "additionalProperties": false, "description": "What the request charged. Partner keys get it on every answer, free ones too." }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "The URL of this error's page in the docs." }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_cursor", "idempotency_key_required", "unauthorized", "payment_required", "partner_key_cap_reached", "partner_tenant_cap_reached", "enterprise_required", "insufficient_scope", "forbidden", "not_offered_to_partner", "not_found", "method_not_allowed", "idempotency_conflict", "operation_in_progress", "conflict", "payload_too_large", "unsupported_media_type", "instagram_not_in_api", "rate_limited", "fetch_quota_exceeded", "partner_fair_use", "fetch_limited", "internal_error", "service_unavailable", "timeout" ], "description": "A stable error code." }, "request_id": { "type": "string", "description": "Also in the X-Request-Id header. Quote it to support." }, "instance": { "type": "string" }, "errors": { "description": "Field problems, for invalid_request.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "cap": { "description": "partner_tenant_cap_reached: the trial cap the request named.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used": { "description": "partner_tenant_cap_reached: the credits the tenant settled since it was created.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scope": { "description": "partner_fair_use: research (credits over 48 hours) or collections (new collections over 30 days).", "type": "string", "enum": [ "research", "collections" ] }, "retry_at": { "description": "partner_fair_use: when the request fits again (ISO 8601, UTC), also in Retry-After.", "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ], "additionalProperties": false } }, "parameters": { "Idempotency-Key": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A unique key per new request (8 to 160 visible ASCII characters, a UUID works). Retrying with the same key returns the first result and never charges twice.", "schema": { "type": "string", "minLength": 8, "maxLength": 160 } } }, "headers": { "X-Request-Id": { "description": "This request's id. Quote it to support.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests allowed per window for this key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The policy, as limit;w=window seconds.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "Idempotent-Replayed": { "description": "true when the response replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } } } } }