openapi: 3.2.0 info: title: Monocrawl Meta Ad Library API version: 0.1.0 description: One key, one envelope, one credit meter across social, search, commerce and web data. contact: name: Monocrawl support url: https://www.monocrawl.com/contact termsOfService: https://www.monocrawl.com/legal/terms-and-conditions servers: - url: https://www.monocrawl.com security: - ApiKeyHeader: [] tags: - name: Meta Ad Library paths: /v1/meta_ads/ad: get: operationId: meta_ads_ad tags: - Meta Ad Library summary: Ad details description: 'One Meta ad by archive id: full creative snapshot, platforms, run dates, and spend/reach where the Ad Library discloses them. Costs 4 credits per successful live response.' parameters: - name: id in: query required: true schema: type: string example: '1702938977100376' description: Ad archive id from a search or company-ads result. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/meta_ads/ad.json title: meta_ads/ad data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: body: description: Optional body supplied by this operation. Null means unknown. type: - string - 'null' cta: description: Optional cta supplied by this operation. Null means unknown. type: - string - 'null' display_format: description: Optional display format supplied by this operation. Null means unknown. type: - string - 'null' ended_at: description: Optional ended at supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} is_active: description: Optional is active supplied by this operation. Null means unknown. type: - boolean - 'null' link_url: description: Optional link url supplied by this operation. Null means unknown. type: - string - 'null' page: description: Optional page supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' publisher_platforms: description: Optional publisher platforms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' started_at: description: Optional started at supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' videos: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} additionalProperties: true allOf: - anyOf: - required: - body properties: body: description: Optional body supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - cta properties: cta: description: Optional cta supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - display_format properties: display_format: description: Optional display format supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - ended_at properties: ended_at: description: Optional ended at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - is_active properties: is_active: description: Optional is active supplied by this operation. Null means unknown. type: - boolean - required: - link_url properties: link_url: description: Optional link url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - page properties: page: description: Optional page supplied by this operation. Null means unknown. type: - object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - publisher_platforms properties: publisher_platforms: description: Optional publisher platforms supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - started_at properties: started_at: description: Optional started at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - videos properties: videos: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - body: example cta: example display_format: example ended_at: '2026-09-01T12:00:00Z' id: example images: [] is_active: false link_url: https://example.com/example page: id: example name: example platform: example publisher_platforms: - example started_at: '2026-09-01T12:00:00Z' title: example videos: [] default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 4 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/meta_ads/ad-transcript: get: operationId: meta_ads_ad_transcript tags: - Meta Ad Library summary: Ad transcript description: The spoken words of a Meta video ad as text. transcript is null when the video has no speech — that is the honest answer, not an error. Costs 5 credits per successful live response. parameters: - name: id in: query required: true schema: type: string example: '4439810673014351' description: Ad archive id of a VIDEO ad. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/meta_ads/ad-transcript.json title: meta_ads/ad-transcript data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: platform: type: - string - 'null' description: meta_ads id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. transcript: type: - string - 'null' description: Source transcript, when available. has_transcript: type: - boolean - 'null' description: Whether usable text was returned. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - transcript properties: transcript: type: - string description: Source transcript, when available. minLength: 1 - required: - has_transcript properties: has_transcript: type: - boolean description: Whether usable text was returned. x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - platform: meta_ads id: example-ad transcript: Illustrative spoken words. has_transcript: true default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 5 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/meta_ads/company-ads: get: operationId: meta_ads_company_ads tags: - Meta Ad Library summary: Company ads description: 'Ads currently or previously running for one advertiser: creative body, title, CTA, link, images/videos, platforms and active state. Paged by cursor. Costs 4 credits per successful live response.' parameters: - name: pageId in: query required: true schema: type: string example: '15087023444' description: Facebook page id from meta_ads/search-companies (or pass companyName instead). - name: companyName in: query required: false schema: type: string description: Company name — alternative to pageId. - name: country in: query required: false schema: type: string example: ALL description: Two-letter country code or ALL. - name: status in: query required: false schema: type: string enum: - ACTIVE - INACTIVE - ALL description: 'ACTIVE, INACTIVE or ALL. Accepted values: ACTIVE, INACTIVE, ALL. Case, spaces, hyphens and underscores are interchangeable.' - name: media_type in: query required: false schema: type: string enum: - ALL - IMAGE - VIDEO - MEME - IMAGE_AND_MEME - NONE description: 'ALL, IMAGE or VIDEO. Accepted values: ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE. Case, spaces, hyphens and underscores are interchangeable.' - name: sort_by in: query required: false schema: type: string enum: - total_impressions - relevancy_monthly_grouped description: 'e.g. total_impressions. Accepted values: total_impressions, relevancy_monthly_grouped. Case, spaces, hyphens and underscores are interchangeable.' - name: start_date in: query required: false schema: type: string description: YYYY-MM-DD. - name: end_date in: query required: false schema: type: string description: YYYY-MM-DD. - name: cursor in: query required: false schema: type: string description: Opaque cursor from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/meta_ads/company-ads.json title: meta_ads/company-ads data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: body: description: Optional body supplied by this operation. Null means unknown. type: - string - 'null' cta: description: Optional cta supplied by this operation. Null means unknown. type: - string - 'null' display_format: description: Optional display format supplied by this operation. Null means unknown. type: - string - 'null' ended_at: description: Optional ended at supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} is_active: description: Optional is active supplied by this operation. Null means unknown. type: - boolean - 'null' link_url: description: Optional link url supplied by this operation. Null means unknown. type: - string - 'null' page: description: Optional page supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' publisher_platforms: description: Optional publisher platforms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' started_at: description: Optional started at supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' videos: description: Optional videos supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - body properties: body: description: Optional body supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - cta properties: cta: description: Optional cta supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - display_format properties: display_format: description: Optional display format supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - ended_at properties: ended_at: description: Optional ended at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - is_active properties: is_active: description: Optional is active supplied by this operation. Null means unknown. type: - boolean - required: - link_url properties: link_url: description: Optional link url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - page properties: page: description: Optional page supplied by this operation. Null means unknown. type: - object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - publisher_platforms properties: publisher_platforms: description: Optional publisher platforms supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - started_at properties: started_at: description: Optional started at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - videos properties: videos: description: Optional videos supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - cursor: null dropped: 0 items: - body: example cta: example display_format: example ended_at: '2026-09-01T12:00:00Z' id: example images: [] is_active: false link_url: https://example.com/example page: id: example name: example platform: example publisher_platforms: - example started_at: '2026-09-01T12:00:00Z' title: example videos: - {} default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 4 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/meta_ads/search: get: operationId: meta_ads_search tags: - Meta Ad Library summary: Ad search description: 'Keyword search across the Meta Ad Library: matching ads with advertiser page, creative snapshot and platforms. Paged by cursor. Costs 4 credits per successful live response.' parameters: - name: query in: query required: true schema: type: string example: running shoes description: Keyword to search ad creatives for. - name: country in: query required: false schema: type: string description: Two-letter country code or ALL. - name: status in: query required: false schema: type: string enum: - ACTIVE - INACTIVE - ALL description: 'ACTIVE, INACTIVE or ALL. Accepted values: ACTIVE, INACTIVE, ALL. Case, spaces, hyphens and underscores are interchangeable.' - name: media_type in: query required: false schema: type: string enum: - ALL - IMAGE - VIDEO - MEME - IMAGE_AND_MEME - NONE description: 'ALL, IMAGE or VIDEO. Accepted values: ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE. Case, spaces, hyphens and underscores are interchangeable.' - name: ad_type in: query required: false schema: type: string description: e.g. all. - name: language in: query required: false schema: type: string example: EN description: Two-letter language code. - name: sort_by in: query required: false schema: type: string enum: - total_impressions - relevancy_monthly_grouped description: 'e.g. total_impressions. Accepted values: total_impressions, relevancy_monthly_grouped. Case, spaces, hyphens and underscores are interchangeable.' - name: start_date in: query required: false schema: type: string description: YYYY-MM-DD. - name: end_date in: query required: false schema: type: string description: YYYY-MM-DD. - name: cursor in: query required: false schema: type: string description: Opaque cursor from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/meta_ads/search.json title: meta_ads/search data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: body: description: Optional body supplied by this operation. Null means unknown. type: - string - 'null' cta: description: Optional cta supplied by this operation. Null means unknown. type: - string - 'null' display_format: description: Optional display format supplied by this operation. Null means unknown. type: - string - 'null' ended_at: description: Optional ended at supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Optional images supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' is_active: description: Optional is active supplied by this operation. Null means unknown. type: - boolean - 'null' link_url: description: Optional link url supplied by this operation. Null means unknown. type: - string - 'null' page: description: Optional page supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' publisher_platforms: description: Optional publisher platforms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' started_at: description: Optional started at supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' videos: description: Optional videos supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - body properties: body: description: Optional body supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - cta properties: cta: description: Optional cta supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - display_format properties: display_format: description: Optional display format supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - ended_at properties: ended_at: description: Optional ended at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Optional images supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - is_active properties: is_active: description: Optional is active supplied by this operation. Null means unknown. type: - boolean - required: - link_url properties: link_url: description: Optional link url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - page properties: page: description: Optional page supplied by this operation. Null means unknown. type: - object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - publisher_platforms properties: publisher_platforms: description: Optional publisher platforms supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - started_at properties: started_at: description: Optional started at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - videos properties: videos: description: Optional videos supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - cursor: null dropped: 0 items: - body: example cta: example display_format: example ended_at: '2026-09-01T12:00:00Z' id: example images: - example is_active: false link_url: https://example.com/example page: id: example name: example platform: example publisher_platforms: - example started_at: '2026-09-01T12:00:00Z' title: example videos: - {} default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 4 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/meta_ads/search-companies: get: operationId: meta_ads_search_companies tags: - Meta Ad Library summary: Advertiser search description: 'Search Meta Ad Library advertisers: page id, name, category, likes, verification and Instagram handle. The page id feeds meta_ads/company-ads. Costs 4 credits per successful live response.' parameters: - name: query in: query required: true schema: type: string example: nike description: Company or brand name. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/meta_ads/search-companies.json title: meta_ads/search-companies data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: category: description: Optional category supplied by this operation. Null means unknown. type: - string - 'null' ig_handle: description: Optional ig handle supplied by this operation. Null means unknown. type: - string - 'null' image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' page_id: description: Optional page id supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true allOf: - anyOf: - required: - category properties: category: description: Optional category supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - ig_handle properties: ig_handle: description: Optional ig handle supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - image properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - likes properties: likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - page_id properties: page_id: description: Optional page id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - verified properties: verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - category: example ig_handle: example image: https://example.com/example likes: 0 name: example page_id: example platform: example verified: false default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 4 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true components: schemas: Error: type: object required: - success - error - credits_used - request_id properties: success: const: false error: type: object required: - type - message - status properties: type: type: string enum: - UNAUTHORIZED - KEY_REVOKED - KEY_LIMIT_EXCEEDED - RATE_LIMITED - INSUFFICIENT_CREDITS - RESOURCE_NOT_FOUND - INVALID_PARAMETERS - TARGET_ACCESS_DENIED - UPSTREAM_ERROR - UPSTREAM_TIMEOUT - FREE_CAPACITY_UNAVAILABLE - CAPACITY_UNAVAILABLE - ENDPOINT_NOT_FOUND - ENDPOINT_NOT_AVAILABLE - FAIR_USE_EXCEEDED - INTERNAL_ERROR message: type: string status: type: integer doc_url: type: string description: Deep link to the exact section of the errors guide for this type. details: type: object credits_used: type: - integer - 'null' description: Confirmed net charge; null when billing is pending reconciliation. Inspect error.details.billing_status and retain request_id. credits_remaining: type: integer request_id: type: string Success: type: object required: - success - platform - endpoint - data - credits_used - credits_remaining - request_id properties: _completeness: type: object description: Reported response completeness, not a guarantee of complete platform history. Missing source assertions remain unknown. properties: state: type: string enum: - complete - partial - unknown scope: type: string inspection_limited: type: boolean success: const: true platform: type: string endpoint: type: string description: The resolved path, e.g. `/v1/github/profile`. data: description: Amazon responses include marketplace.country and marketplace.domain (resolved request marketplace, UK by default). X profiles preserve location, bio_link and cover_url when supplied. TikTok profiles preserve commerce_user, seller, region, location and business_category when supplied; region identifies the account region rather than personal residence. TikTok comments use platform_default selection, which can change between fetches; keep the same video and options when following cursors. Amazon review variant is readable text. Facebook profiles preserve cover_url, following and created_at when supplied; likes_count and followers are distinct and follower totals may be rounded. Endpoint-specific normalized payload, not one universal post/profile schema. Many lists use items/count/cursor; a null cursor means no usable next cursor was supplied, not proof that all history was retrieved. Check has_more and warnings where present. Social full-profile bundles use posts_cursor and posts_pagination.next_params; retain all returned next parameters. YouTube channel bundles instead use recent_videos, cursor and recent_videos_pagination. Inspect complete/partial/legs where supplied for bounded or failed components. Optional model-derived fields are labelled, not source facts. credits_used: type: integer credits_remaining: type: integer request_id: type: string cached: type: boolean stale: type: boolean description: True only for an explicitly labelled, zero-credit reference snapshot served after a temporary upstream failure. age_seconds: type: integer minimum: 0 description: Age of a stale snapshot since its original retrieval; not reset by outage recovery. fetched_at: type: string format: date-time description: Original retrieval time of a stale snapshot, in UTC. synthetic: type: boolean description: Present and true only on the explicitly requested /sandbox surface. Synthetic responses are representative and charged 0 credits; production /v1 never returns them. degraded: type: boolean description: Reserved for sandbox compatibility. Production /v1 reports upstream failure as an error and never serves a representative fallback. securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key description: Your API key (`mn_…`), from the console. The recommended style. BearerKey: type: http scheme: bearer description: The same key as a Bearer token, for clients that only expose an Authorization field. Keys are never accepted in the query string — URLs leak into logs and referrers. x-provenance: method: harvested publisher: Monocrawl source: https://www.monocrawl.com/openapi.json note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)