> ## Documentation Index
> Fetch the complete documentation index at: https://docs.copyfy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# lookup

> Resolve a link you paste (a store, a product page, a Meta Ad Library ad, or a Copyfy shop page) to its Copyfy data.

Resolves a link to its record in Copyfy, so you can paste a store, a product page, or a Meta ad and get its data in one call. The result's `type` says what the link points to: `shop`, `product`, or `ad`. Use it when you have a link instead of a Copyfy id.

**Cost:** 1 credit per successful call.

## Arguments

| Argument | Type | Allowed values |
| - | - | - |
| `url` | string | A link or a bare domain, in one of the formats below. Required. |

## Supported links

| Link | Example | Returns |
| - | - | - |
| Store URL or domain | `https://example-pet-store.com/collections/all` or `example-pet-store.com` | `type: "shop"` and the store, as [`get_shop`](https://docs.copyfy.io/tools/get-shop) returns it. |
| Product URL | `https://example-pet-store.com/products/self-cleaning-slicker-brush` | `type: "product"` and the product, as [`get_product`](https://docs.copyfy.io/tools/get-product) returns it. See [Product links](#product-links). |
| Meta Ad Library ad URL | `https://www.facebook.com/ads/library/?id=1187340029915522` | `type: "ad"`, the ad as [`search_ads`](https://docs.copyfy.io/tools/search-ads) describes it, and its store. |
| Copyfy shop URL | `https://app.copyfy.io/dashboard/track/902114` | `type: "shop"` and the store, as [`get_shop`](https://docs.copyfy.io/tools/get-shop) returns it. |

Product URLs also work behind a collection or market prefix, such as `/collections/dogs/products/<handle>` or `/fr/products/<handle>`. Copyfy ignores query strings and tracking parameters (`utm_source`, `fbclid`, `variant`, and so on), except the `id` of an Ad Library link.

## Product links

Product details follow the same access rule as [`get_product`](https://docs.copyfy.io/tools/get-product): they are returned for stores you track in Copyfy and for your own brand stores. For other stores, the result has the product's short sheet (`id`, `title`, `url`, `currency`, `price_min`, `price_max`, the main image, dates, `shop` and `dashboard_url`), the store as `get_shop` returns it, and `product_details_require_tracking: true`. Track the store from its `dashboard_url`, then call `get_product` with the product `id`. The MCP never uses your tracking slots on its own.

## Example

```json Tool call theme={null}
{
  "name": "lookup",
  "arguments": { "url": "https://www.facebook.com/ads/library/?id=1187340029915522" }
}
```

```json Result for an ad (trimmed) theme={null}
{
  "type": "ad",
  "ad": {
    "id": 5521907,
    "ad_archive_id": "1187340029915522",
    "page_name": "Example Pet Store",
    "status": "active",
    "media_type": "video",
    "headline": "Fur-free in one click",
    "cta": "Shop Now",
    "landing_url": "https://example-pet-store.com/products/self-cleaning-slicker-brush",
    "video_url": "https://bucket.copyfy.io/media/1187340029915522/clip.mp4",
    "ad_library_url": "https://www.facebook.com/ads/library/?id=1187340029915522",
    "started_at": "2026-07-14T00:00:00.000Z",
    "active_days": 104,
    "shop": { "id": 902114, "name": "Example Pet Store", "domain": "example-pet-store.com", "country": "US", "active_ads": 37 },
    "dashboard_url": "https://app.copyfy.io/dashboard/track/902114"
  },
  "shop": {
    "id": 902114,
    "name": "Example Pet Store",
    "domain": "example-pet-store.com",
    "estimated_monthly_revenue": 214800,
    "monthly_visits": 184000,
    "active_ads": 37,
    "is_tracked": false,
    "tracking_required_for_full_analytics": true
  }
}
```

```json Result for a product of a store you do not track (trimmed) theme={null}
{
  "type": "product",
  "product": {
    "id": 48213377,
    "title": "Self-Cleaning Slicker Brush",
    "url": "https://example-pet-store.com/products/self-cleaning-slicker-brush",
    "currency": "USD",
    "price_min": 24.99,
    "price_max": 29.99,
    "image_urls": ["https://cdn.shopify.com/s/files/1/example/brush.jpg"],
    "shop": { "id": 902114, "domain": "example-pet-store.com" },
    "dashboard_url": "https://app.copyfy.io/dashboard/track/902114",
    "details_require_tracking": true
  },
  "product_details_require_tracking": true,
  "shop": {
    "id": 902114,
    "name": "Example Pet Store",
    "domain": "example-pet-store.com",
    "estimated_monthly_revenue": 214800,
    "is_tracked": false,
    "tracking_required_for_full_analytics": true
  }
}
```

## Result fields

| Field | Type | Description |
| - | - | - |
| `type` | string | `shop`, `product`, or `ad`. |
| `shop` | object or null | The store, with the [`get_shop` result fields](https://docs.copyfy.io/tools/get-shop#result-fields). Absent for a product whose details you can see. `null` for an ad whose store Copyfy cannot load. |
| `product` | object | For `type: "product"`: the [`get_product` result fields](https://docs.copyfy.io/tools/get-product#result-fields), or the short sheet (title, link, price range, currency, main image) when product details require tracking. |
| `product_details_require_tracking` | boolean | Present and `true` when you do not track the product's store. |
| `ad` | object | For `type: "ad"`: the [`search_ads` result fields](https://docs.copyfy.io/tools/search-ads#result-fields). |

Unlike `search_ads`, `lookup` also returns ads whose media Copyfy has not stored yet: `video_url` is then `null`, and `image_url` can be a Meta link that expires within days.

## Errors

A link in another format, such as free text, a Facebook page, or a Copyfy page other than a shop page, returns [`invalid_arguments`](https://docs.copyfy.io/errors#invalid_arguments) with the `supported_formats`. A store, product, or ad that Copyfy does not know returns [`not_found`](https://docs.copyfy.io/errors#not_found). For a product of a store Copyfy knows, the error includes the store's `shop_id` and `dashboard_url`. Refused calls are free.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.