# Top ads by impressions for a keyword

**Use case:** 

Find who's advertising for any topic. Drop in a Meta Ad Library keyword URL and scrape every matching advertiser's ads, sorted by top impressions first.

## Input

```json
{
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&content_languages[0]=en&country=ALL&is_targeted_country=false&media_type=all&q=protein%20powder&search_type=keyword_unordered&sort_data[mode]=total_impressions&sort_data[direction]=desc"
    }
  ],
  "resultsLimit": 10,
  "onlyTotal": false,
  "includeAboutPage": false,
  "isDetailsPerAd": false,
  "activeStatus": "active",
  "sorting": "total_impressions",
  "onlyAdsNewerThan": "2024-01-01",
  "onlyAdsOlderThan": "2024-12-31",
  "enrichWithEcommerceData": false
}
```

## Output

```json
{
  "pageInfo.page.name": {
    "label": "Page name"
  },
  "pageInfo.page.about.text": {
    "label": "Page about"
  },
  "totalCount": {
    "label": "Total count",
    "format": "number"
  },
  "snapshot.title": {
    "label": "Ad text",
    "format": "string"
  },
  "snapshot.displayFormat": {
    "label": "Ad format",
    "format": "string"
  },
  "isActive": {
    "label": "Is active",
    "format": "boolean"
  },
  "spend": {
    "label": "Spent",
    "format": "object"
  },
  "reachEstimate": {
    "label": "Reach estimate",
    "format": "object"
  },
  "impressions": {
    "label": "Impressions",
    "format": "object"
  },
  "publisherPlatform": {
    "label": "Published at",
    "format": "array"
  },
  "startDateFormatted": {
    "label": "Start date",
    "format": "string"
  },
  "endDateFormatted": {
    "label": "End date",
    "format": "string"
  },
  "ageGenderData": {
    "label": "Age gender data",
    "format": "array"
  },
  "locationData": {
    "label": "Location data",
    "format": "array"
  }
}
```

## About this Actor

This example demonstrates how to use [Facebook Ads Library Scraper](https://apify.com/apify/facebook-ads-scraper.md) with a specific input configuration. Visit the [Actor detail page](https://apify.com/apify/facebook-ads-scraper.md) to learn more, explore other use cases, and run it yourself.


## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
This Task's input is already configured above — use it as-is rather than inventing a new one.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For full API examples (JavaScript, Python, CLI, MCP, OpenAPI), see this Task's Actor page: https://apify.com/apify/facebook-ads-scraper.md

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).