# Search Ad Library companies > Find an advertiser's Facebook page id by name in Meta's Ad Library, with followers and linked Instagram. - **Request:** `GET https://api.lurkapi.com/v1/facebook/adLibrary/search/companies` - **Auth:** `x-api-key` header ([get a free key](https://lurkapi.com/login?next=/dashboard)) - **Cost:** 1 credit per call. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)). - **MCP tool:** `facebook_search_companies` on `https://api.lurkapi.com/mcp` - **Freshness:** responses are cached for up to 1 day - **Try it live:** https://lurkapi.com/docs/facebook/search-companies#try (no signup) - **Platform:** [Facebook](https://lurkapi.com/docs/facebook.md) (facebook.com/ads/library) - **Web page:** https://lurkapi.com/docs/facebook/search-companies ## When to use this Use it to turn a brand name into the `page_id` that company ads (facebook_company_ads) needs. Big brands have several pages (regional, product lines); pick by `name`, `likes` and `verification`. Typeahead search over advertisers in the Ad Library, like the search box on facebook.com/ads/library. Returns up to about 15 matches, no pagination. ## Parameters All parameters go in the query string. | Name | Type | Required | Default | Allowed values | Description | Example | | --- | --- | --- | --- | --- | --- | --- | | `query` | string | yes | | | Brand or page name, e.g. `nike`. | `nike` | | `country` | string | no | `US` | | 2-letter country code that biases which pages rank first, or ALL. | | ## Example request Replace `YOUR_API_KEY` with your key, or set `LURKAPI_KEY` for the code. [Get a free key](https://lurkapi.com/login?next=/dashboard). curl: ```bash curl "https://api.lurkapi.com/v1/facebook/adLibrary/search/companies?query=nike" \ -H "x-api-key: YOUR_API_KEY" ``` JavaScript: ```js const params = new URLSearchParams({ query: "nike", }); const res = await fetch(`https://api.lurkapi.com/v1/facebook/adLibrary/search/companies?${params}`, { headers: { "x-api-key": process.env.LURKAPI_KEY }, }); const data = await res.json(); if (!data.success) throw new Error(`${data.code}: ${data.error}`); console.log(data.searchResults); ``` Python: ```python import os import requests res = requests.get( "https://api.lurkapi.com/v1/facebook/adLibrary/search/companies", params={ "query": "nike", }, headers={"x-api-key": os.environ["LURKAPI_KEY"]}, timeout=60, ) data = res.json() if not data["success"]: raise RuntimeError(f"{data['code']}: {data['error']}") print(data["searchResults"]) ``` ## Example response A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in `…`. 200 OK (application/json): ```json { "success": true, "credits_remaining": 996, "credits_charged": 1, "searchResults": [ { "category": "Sportswear Store", "country": null, "entity_type": "PERSON_PROFILE", "ig_followers": 291075731, "ig_username": "nike", "ig_verification": true, "image_uri": "https://scontent.fbts1-1.fna.fbcdn.net/v/t39.30808-1/284964043_101599038…", "likes": 39514042, "name": "Nike", "page_alias": "nike", "page_id": "15087023444", "page_is_deleted": false, "verification": "BLUE_VERIFIED" }, { "category": "Product/service", "country": null, "entity_type": "PERSON_PROFILE", "ig_followers": 44794371, "ig_username": "nikefootball", "ig_verification": true, "image_uri": "https://scontent.fbts1-1.fna.fbcdn.net/v/t39.30808-1/387181570_863325755…", "likes": 40028551, "name": "Nike Football", "page_alias": "nikefootball", "page_id": "51212153078", "page_is_deleted": false, "verification": "BLUE_VERIFIED" } ] } ``` ## Response fields Every field of a successful response. `[]` marks a list: `a[].b` is the `b` of each item in `a`. **nullable** fields can be `null`; **optional** fields can be missing. | Field | Type | Description | | --- | --- | --- | | `success` | `true` | Always true here; errors have `success: false`. | | `credits_remaining` | `number` | Your balance after this call. On anonymous playground calls: free tries left today. | | `credits_charged` | `number` | Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1). | | `searchResults` | `object[]` | Matching advertiser pages, best match first. | | `searchResults[].page_id` | `string`, nullable | The page id. Pass it as `pageId` to the company ads endpoint. | | `searchResults[].name` | `string`, nullable | The page's name. | | `searchResults[].page_alias` | `string`, nullable | Vanity name: facebook.com/. | | `searchResults[].category` | `string`, nullable | Page category, e.g. "Sportswear Store". | | `searchResults[].likes` | `number`, nullable | Page followers. | | `searchResults[].verification` | `string`, nullable | BLUE_VERIFIED or NOT_VERIFIED. | | `searchResults[].image_uri` | `string`, nullable | Profile picture URL. | | `searchResults[].ig_username` | `string`, nullable | Linked Instagram username, without @; null when none is linked. | | `searchResults[].ig_followers` | `number`, nullable | Followers of the linked Instagram account; null when none is linked. | | `searchResults[].ig_verification` | `boolean` | Whether the linked Instagram account is verified; false when none is linked. | | `searchResults[].country` | `string`, nullable | The page's country; null in every response we've seen. | | `searchResults[].entity_type` | `string`, nullable | Facebook's page type; PERSON_PROFILE for most pages, brands included. | | `searchResults[].page_is_deleted` | `boolean` | Whether the page has been deleted. | ## Caching and freshness Responses are cached for up to 1 day, so a repeat call within that window can return the same data. It still costs 1 credit. ## Errors Errors return `{ success: false, error, code, docs }` with the HTTP status below. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)). [All error codes](https://lurkapi.com/docs.md#errors). | Status | Code | Meaning | | --- | --- | --- | | 401 | `missing_api_key` | No API key. Send it in the `x-api-key` header. | | 401 | `invalid_api_key` | The key is unknown or was revoked. | | 402 | `insufficient_credits` | Not enough credits for this call. Buy a pack or wait for tomorrow's top-up. | | 405 | `method_not_allowed` | Endpoints take GET with query params. | | 429 | `rate_limited` | Too many calls at once. Wait for the `retry-after` seconds, then retry. | | 500 | `internal_error` | Something broke on our side. Retry; 5xx errors are free. | | 502 | `upstream_error` | The platform didn't give a usable answer. Retry; 5xx errors are free. | | 503 | `upstream_busy` | All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free. | | 504 | `upstream_timeout` | The platform took over 30 seconds to answer. Retry; timeouts are free. | ## Use it in Claude Once LurkAPI is [connected to Claude](https://lurkapi.com/docs.md#claude), this endpoint is the `facebook_search_companies` tool. Ask in plain English, for example: Ask Claude: ```text Use LurkAPI's facebook_search_companies with query "nike" and summarize what you find. ``` Claude calls `facebook_search_companies` with arguments like these, and each call costs 1 credit: Tool arguments: ```json { "query": "nike" } ``` Tool results skip nulls and empty lists to save tokens. --- Previous: [Ad Library ad details](https://lurkapi.com/docs/facebook/ad.md) · Next: [Public profile](https://lurkapi.com/docs/facebook/profile.md)