openapi: 3.0.0 info: title: Meta Ad Library Ad Details API description: | This API retrieves detailed information about a specific ad from the Meta Ad Library, including advertiser page information, audience insights, and EU/UK transparency data for ads shown in those regions. **Cross-linking**: Use the Meta Ad Library API to search for ads. Each returned ad includes an ad_details_token and an ad_archive_id that can be passed to this API. The page_id parameter can also be obtained from the Meta Ad Library Page Search API or the Meta Ad Library Page Info API. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Meta Ad Library Ad Details Search security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Engine to use for the search schema: type: string enum: ["meta_ad_library_ad_details"] - name: ad_archive_id in: query required: false description: Unique ID of the ad. Obtain it from the Meta Ad Library API response or from the "Library ID" shown on ad cards in the Meta Ad Library website. Required when ad_details_token is not provided. schema: type: string - name: ad_details_token in: query required: false description: Recommended. Token from the ad_details_token field on each ad returned by the Meta Ad Library API. It encodes ad_archive_id, page_id, country, and is_political, providing better results for political ads and EU/UK transparency data. schema: type: string - name: is_political in: query required: false description: Whether the ad is a political or issue ad schema: type: boolean default: false - name: country in: query required: false description: Country to scope transparency data by schema: type: string enum: ["ALL", "US", "CA", "GB", "AR", "AU", "AT", "BE", "BR", "CL", "CN", "CO", "HR", "DK", "DO", "EG", "FI", "FR", "DE", "GR", "HK", "IN", "ID", "IE", "IL", "IT", "JP", "JO", "KW", "LB", "MY", "MX", "NL", "NZ", "NG", "NO", "PK", "PA", "PE", "PH", "PL", "RU", "SA", "RS", "SG", "ZA", "KR", "ES", "SE", "CH", "TW", "TH", "TR", "AE", "VE", "PT", "LU", "BG", "CZ", "SI", "IS", "SK", "LT", "TT", "BD", "LK", "KE", "HU", "MA", "CY", "JM", "EC", "RO", "BO", "GT", "CR", "QA", "SV", "HN", "NI", "PY", "UY", "PR", "BA", "PS", "TN", "BH", "VN", "GH", "MU", "UA", "MT", "BS", "MV", "OM", "MK", "LV", "EE", "IQ", "DZ", "AL", "NP", "MO", "ME", "SN", "GE", "BN", "UG", "GP", "BB", "AZ", "TZ", "LY", "MQ", "CM", "BW", "ET", "KZ", "NA", "MG", "NC", "MD", "FJ", "BY", "JE", "GU", "YE", "ZM", "IM", "HT", "KH", "AW", "PF", "AF", "BM", "GY", "AM", "MW", "AG", "RW", "GG", "GM", "FO", "LC", "KY", "BJ", "AD", "GD", "VI", "BZ", "VC", "MN", "MZ", "ML", "AO", "GF", "UZ", "DJ", "BF", "MC", "TG", "GL", "GA", "GI", "CD", "KG", "PG", "BT", "KN", "SZ", "LS", "LA", "LI", "MP", "SR", "SC", "VG", "TC", "DM", "MR", "AX", "SM", "SL", "NE", "CG", "AI", "YT", "CV", "GN", "TM", "BI", "TJ", "VU", "SB", "ER", "WS", "AS", "FK", "GQ", "TO", "KM", "PW", "FM", "CF", "SO", "MH", "VA", "TD", "KI", "ST", "TV", "NR", "RE", "LR", "ZW", "CI", "MM", "AN", "AQ", "BQ", "BV", "IO", "CX", "CC", "CK", "CW", "TF", "GW", "HM", "XK", "MS", "NU", "NF", "PN", "BL", "SH", "MF", "PM", "SX", "GS", "SS", "SJ", "TL", "TK", "UM", "WF", "EH"] default: "ALL" - name: page_id in: query required: false description: ID of the advertiser's Facebook page. Obtain it from the Meta Ad Library, Meta Ad Library Page Search, or Meta Ad Library Page Info APIs. When provided, the response includes advertiser page information and location-scoped transparency data. schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' advertiser: $ref: '#/components/schemas/Advertiser' insights: $ref: '#/components/schemas/Insights' aaa_info: $ref: '#/components/schemas/AaaInfo' transparency_by_location: $ref: '#/components/schemas/TransparencyByLocation' br_info: type: object description: Brazil transparency information when the ad targets Brazil violation_types: type: array items: type: string description: Types of policy violations associated with the ad is_violating_eu_siep: type: boolean description: Whether the ad violates EU rules for social issues, elections, or politics (SIEP) ads verified_voice_context: $ref: '#/components/schemas/VerifiedVoiceContext' error: type: string description: Error message if the API didn't return results SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Meta Ad Library URL for this search html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: Engine used for the search ad_archive_id: type: string description: Ad archive ID used in the search is_political: type: string description: Whether the ad was requested as a political or issue ad country: type: string description: Country used in the search page_id: type: string description: Page ID used in the search ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong Advertiser: type: object description: Information about the advertiser behind the ad. Returned when page_id is provided. properties: page: $ref: '#/components/schemas/AdvertiserPage' ad_library_page_info: $ref: '#/components/schemas/AdLibraryPageInfo' AdvertiserPage: type: object properties: id: type: string description: Facebook page ID about: type: object properties: text: type: string description: About text of the page is_delegate_page_with_linked_primary_profile: type: boolean description: Whether the page is a delegate page linked to a primary profile AdLibraryPageInfo: type: object properties: page_spend: $ref: '#/components/schemas/PageSpend' page_info: $ref: '#/components/schemas/PageInfo' PageSpend: type: object properties: current_week: type: number description: Ad spend for the current week lifetime_by_disclaimer: type: array items: $ref: '#/components/schemas/DisclaimerSpend' description: Lifetime ad spend broken down by disclaimer weekly_by_disclaimer: type: array items: $ref: '#/components/schemas/DisclaimerSpend' description: Weekly ad spend broken down by disclaimer is_political_page: type: boolean description: Whether the page runs political ads DisclaimerSpend: type: object properties: disclaimer: type: string description: Disclaimer text identifying who paid for the ads spend: type: number description: Amount spent under this disclaimer PageInfo: type: object properties: page_id: type: string description: Facebook page ID page_name: type: string description: Name of the page page_alias: type: string description: Alias of the page page_category: type: string description: Category of the page page_profile_uri: type: string description: URL of the page profile page_cover_photo: type: string description: URL of the page cover photo profile_photo: type: string description: URL of the page profile photo page_verification: type: string description: Verification status of the page page_is_deleted: type: boolean description: Whether the page has been deleted page_is_restricted: type: boolean description: Whether the page is restricted is_profile_page: type: boolean description: Whether the page is a profile page entity_type: type: string description: Type of the entity behind the page likes: type: integer description: Number of page likes ig_username: type: string description: Linked Instagram username ig_followers: type: integer description: Number of Instagram followers ig_verification: type: boolean description: Whether the Instagram account is verified Insights: type: object description: Audience insights for political and issue ads properties: age_gender_data: type: array items: $ref: '#/components/schemas/AgeGenderData' description: Audience reach distribution by age range and gender currency_matched: type: boolean description: Whether the spend currency matches the ad's currency location_data: type: array items: $ref: '#/components/schemas/LocationData' description: Audience reach distribution by region single_country: type: string description: ISO country code when the ad ran in a single country AgeGenderData: type: object properties: age_range: type: string description: Age range bucket male: type: number description: Reach share for males in this age range female: type: number description: Reach share for females in this age range unknown: type: number description: Reach share for unknown gender in this age range LocationData: type: object properties: region: type: string description: Name of the region reach: type: number description: Reach share in this region AaaInfo: type: object description: '"About this Ad" transparency information for ads shown in the EU, EEA, or UK' properties: targets_eu: type: boolean description: Whether the ad targets EU audiences location_audience: type: array items: $ref: '#/components/schemas/LocationAudience' description: Locations included or excluded from the ad's audience targeting gender_audience: type: string description: Gender targeting of the ad age_audience: $ref: '#/components/schemas/AgeAudience' eu_total_reach: type: integer description: Total reach of the ad in the EU age_country_gender_reach_breakdown: type: array items: $ref: '#/components/schemas/CountryReachBreakdown' description: Reach breakdown by country, age range, and gender payer_beneficiary_data: type: array items: $ref: '#/components/schemas/PayerBeneficiary' description: Who paid for and who benefits from the ad has_violating_payer_beneficiary: type: boolean description: Whether the payer or beneficiary information violates policies is_ad_taken_down: type: boolean description: Whether the ad has been taken down AgeAudience: type: object properties: min: type: integer description: Minimum targeted age max: type: integer description: Maximum targeted age LocationAudience: type: object properties: name: type: string description: Name of the targeted location type: type: string description: Type of the targeted location excluded: type: boolean description: Whether the location is excluded from targeting num_obfuscated: type: integer description: Number of obfuscated locations CountryReachBreakdown: type: object properties: country: type: string description: ISO country code age_gender_breakdowns: type: array items: $ref: '#/components/schemas/AgeGenderBreakdown' description: Reach by age range and gender within this country AgeGenderBreakdown: type: object properties: age_range: type: string description: Age range bucket male: type: integer description: Reach for males in this age range female: type: integer description: Reach for females in this age range unknown: type: integer description: Reach for unknown gender in this age range PayerBeneficiary: type: object properties: payer: type: string description: Entity that paid for the ad beneficiary: type: string description: Entity that benefits from the ad TransparencyByLocation: type: object description: Transparency data scoped by location. Returned when page_id and country are provided. properties: br_transparency: type: object description: Brazil transparency data when the ad targets Brazil eu_transparency: $ref: '#/components/schemas/EuTransparency' uk_transparency: $ref: '#/components/schemas/UkTransparency' EuTransparency: type: object description: EU transparency data properties: targets_eu: type: boolean description: Whether the ad targets EU audiences location_audience: type: array items: $ref: '#/components/schemas/LocationAudience' description: Locations included or excluded from the ad's audience targeting gender_audience: type: string description: Gender targeting of the ad age_audience: $ref: '#/components/schemas/AgeAudience' eu_total_reach: type: integer description: Total reach of the ad in the EU age_country_gender_reach_breakdown: type: array items: $ref: '#/components/schemas/CountryReachBreakdown' description: Reach breakdown by country, age range, and gender UkTransparency: type: object description: UK transparency data properties: location_audience: type: array items: $ref: '#/components/schemas/LocationAudience' description: Locations included or excluded from the ad's audience targeting gender_audience: type: string description: Gender targeting of the ad age_audience: $ref: '#/components/schemas/AgeAudience' total_reach: type: integer description: Total reach of the ad in the UK age_country_gender_reach_breakdown: type: array items: $ref: '#/components/schemas/CountryReachBreakdown' description: Reach breakdown by country, age range, and gender VerifiedVoiceContext: type: object description: Verified voice context for the ad properties: types: type: array items: type: string description: Verified voice types associated with the ad ad_library_all_geo_fin_serv_info: type: object description: Financial services information for the ad