# LinkedIn Ads Search

Search the public LinkedIn Ad Library by keyword, country, and date range. Returns ad rows with their numeric ad IDs so you can request full ad details. One request performs exactly one upstream lookup, so one credit buys one page. When more results exist the response carries pagination_token; send it back as pagination_token on the next request, which is a separate, separately billed lookup. upstream_calls reports the real upstream request count and exceeds 1 only when a request was refused and retried, which is a retry of the same page rather than a fan-out and costs no extra credit. An Ad Library page that returns no ads is never billed. The Errors section lists the common cases rather than every code: any failed request carries an error_code, and none of them is billed.

- **Documentation:** [https://scrappa.co/docs/linkedin-api/linkedin_ads_search](https://scrappa.co/docs/linkedin-api/linkedin_ads_search)
- **API group:** LinkedIn API
- **Endpoint:** `GET https://scrappa.co/api/linkedin/ads/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `keyword` | string | Yes | Search phrase. |
| `countries[]` | string | No | Repeatable 2-letter country code (e.g., countries[]=US&countries[]=DE). |
| `dateOption` | string | No | last-30-days or custom-date-range. |
| `startdate` | string | No | Range start as YYYY-MM-DD. Only used with custom-date-range. |
| `enddate` | string | No | Range end as YYYY-MM-DD. Only used with custom-date-range. |
| `accountOwner` | string | No | Restrict results to one advertiser. |
| `pagination_token` | string | No | Continuation token from a previous response, for the next page. It is one separately billed lookup. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/linkedin/ads/search?keyword=analytics+platform&countries%5B0%5D=US"
```

## Example response

```json
{
    "ads": [
        {
            "ad_id": "541239876501",
            "url": "https://www.linkedin.com/ad-library/detail/541239876501"
        }
    ],
    "ad_count": 1,
    "upstream_calls": 1,
    "is_last_page": false,
    "pagination_token": "next-page-token"
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | The keyword parameter is missing, or a filter value is out of range. |
| 404 | No Ads Found | LinkedIn returned an Ad Library page with no ads, which means this search matched nothing or the pagination token reached the end of the result set. Not billed. |
| 403 | Ad Library Refused | LinkedIn answered with a full-size page carrying no ads, which is how it refuses a blocked request. Retrying usually succeeds. Not billed, so this is never mistaken for a search that matched nothing. |
| 503 | Upstream Error | LinkedIn answered with a non-success status that is neither a refusal wall nor an empty result. Failed requests are never billed. |
| 503 | Request Not Dispatched | Scrappa could not send this request to LinkedIn at all, so no data was retrieved. Please try again in a moment. Failed requests are never billed. |
| 503 | Transport Unavailable | The request never produced a usable answer, so the retrieval path was unavailable. Failed requests are never billed. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)