---
type: "firecrawl-provider"
description: "Find Tools catalogue lookup, plus reviewed website skills for agents and Interact."
use_when: "Promo codes for one store from Firecrawl's coupon programs in one call, deduplicated and ranked.\n\nFind providers, open groups, inspect a tool, then execute it separately."
categories: "Tools"
capabilities: 1
credits_per_call: 0
---
# Firecrawl on Firecrawl Alexandria

Find Tools catalogue lookup, plus reviewed website skills for agents and Interact.

- Categories: Tools
- Category index: [Tools category](https://alexandria.firecrawl.dev/agents/categories/tools)
- Provider key: `firecrawl`
- Access: Firecrawl credits
- Cost: 0 credits per call

## More

- [Human guide](https://www.firecrawl.dev/app/alexandria/firecrawl)
- [OpenAPI spec](https://alexandria.firecrawl.dev/agents/providers/firecrawl/openapi.json)

## 1. Choose this provider when

Promo codes for one store from Firecrawl's coupon programs in one call, deduplicated and ranked.

Find providers, open groups, inspect a tool, then execute it separately.

## 2. Minimal request

Call `POST https://api.firecrawl.dev/v2/scrape` with `{ alexandria: { provider, capability, options } }`. For a batch, send `{ alexandria: [...] }` with up to 10 calls.

```json
{
  "provider": "firecrawl",
  "capability": "coupon-waterfall",
  "options": {
    "store": "<store>",
    "mode": "first_hit",
    "min_codes": 1,
    "max_credits": 25
  }
}
```

## 3. Add provider options

Use only the options needed for the task:

- `store` (string, required): Store domain (brooklinen.com), a store URL, or a store name (Home Depot, 楽天). Reduced to a bare domain, a stem and a display name. A name with no Latin letters or digits has no slug, so slug-keyed providers wait until a provider reports the store's domain. Example: `<store>`
- `country` (string): Market that picks the default provider order. Default: from the domain's TLD (.co.uk GB, .de DE, .com.au AU), otherwise US. Example: `US`
- `mode` (string): first_hit asks one provider at a time and stops at min_codes codes. merge asks every planned provider in parallel. Example: `first_hit`
- `min_codes` (number): first_hit only. Unique unexpired codes needed to stop; with include_expired, expired codes are returned but never count. Example: `1`
- `providers` (string[]): Only these providers, in this order: couponfollow-com, joinhoney-com, promocodes-com, coupons-com, savings-com, dealsea-com, dealnews-com, hotukdeals-com, mydealz-de, ozbargain-com-au. Default: the country's order. Example: `[]`
- `include_expired` (boolean): Also return codes a provider marks expired or whose expiry date has passed. Example: `false`
- `resolve_stores` (boolean): When a guessed slug misses on promocodes-com or coupons-com, spend one search_stores call to find the store's slug. Billed even when it finds nothing. Example: `false`
- `max_credits` (number): Most provider credits the whole call may spend. A provider is started only while its price still fits. Example: `25`

## 4. Request through your preferred interface

### JavaScript

```javascript
const result = await firecrawl.scrape({
  alexandria: {
    provider: "firecrawl",
    capability: "coupon-waterfall",
    options: {
      store: "<store>",
      mode: "first_hit",
      min_codes: 1,
      max_credits: 25,
    },
  },
});
```

### Python

```python
result = firecrawl.scrape_alexandria({
  "provider": "firecrawl",
  "capability": "coupon-waterfall",
  "options": {
    "store": "<store>",
    "mode": "first_hit",
    "min_codes": 1,
    "max_credits": 25
  }
})
```

### cURL

```sh
curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "alexandria": {
    "provider": "firecrawl",
    "capability": "coupon-waterfall",
    "options": {
      "store": "<store>",
      "mode": "first_hit",
      "min_codes": 1,
      "max_credits": 25
    }
  }
}'
```

### CLI

```sh
firecrawl scrape 'firecrawl/coupon-waterfall' \
  --options '{"store":"<store>","mode":"first_hit","min_codes":1,"max_credits":25}'
```


### MCP

Call the FCX MCP retrieve tool with this object:

```json
{
  "provider": "firecrawl",
  "capability": "coupon-waterfall",
  "options": {
    "store": "<store>",
    "mode": "first_hit",
    "min_codes": 1,
    "max_credits": 25
  }
}
```

Ask for only the returned fields needed by the task.

## 5. Full request shape

```json
{
  "provider": "firecrawl",
  "capability": "coupon-waterfall",
  "options": {
    "store": "<store>",
    "mode": "first_hit",
    "min_codes": 1,
    "max_credits": 25
  }
}
```

## 6. Response data

The response includes `success`, `provider`, `capability`, `creditsCost` and `data`. This example shows the provider payload in `data`:

```json
{
  "status": "<status>",
  "store": {},
  "coupons": [],
  "tried": [],
  "summary": {},
  "providerCredits": 0,
  "maxCredits": 0,
  "billingComplete": false,
  "billingNotice": "<billingNotice>",
  "observed_at": "<observed_at>"
}
```

## API reference-derived contract

The following capability contract is generated from the same normalized Alexandria API reference exposed in the API spec.

### Coupon waterfall

- Capability: `coupon-waterfall`
- Description: Deduplicated codes with each provider's evidence, and every provider asked. status is hit, miss, error, budget_exhausted, stopped or no_provider; never treat stopped as a miss. error means every provider asked failed; a miss with summary.providers_failed is not a full miss.
- Instructions: Find the promo codes a store has right now from a domain, store URL or store name. Firecrawl's coupon programs are asked in order (the regional one first for .co.uk, .de and .com.au stores), and the codes they return are deduplicated on the code and merged, with each program's own signals kept under sources. first_hit stops once min_codes codes are in hand; merge asks every program that fits max_credits. Nothing is checked at a checkout. Provider calls are billed separately; the wrapper is free.
- Cost: 0 credits per call
- Capability file: [Coupon waterfall](https://alexandria.firecrawl.dev/agents/providers/firecrawl/coupon-waterfall)

Accepted options:
- `store` (string, required): Store domain (brooklinen.com), a store URL, or a store name (Home Depot, 楽天). Reduced to a bare domain, a stem and a display name. A name with no Latin letters or digits has no slug, so slug-keyed providers wait until a provider reports the store's domain. Example: `<store>`
- `country` (string): Market that picks the default provider order. Default: from the domain's TLD (.co.uk GB, .de DE, .com.au AU), otherwise US. Example: `US`
- `mode` (string): first_hit asks one provider at a time and stops at min_codes codes. merge asks every planned provider in parallel. Example: `first_hit`
- `min_codes` (number): first_hit only. Unique unexpired codes needed to stop; with include_expired, expired codes are returned but never count. Example: `1`
- `providers` (string[]): Only these providers, in this order: couponfollow-com, joinhoney-com, promocodes-com, coupons-com, savings-com, dealsea-com, dealnews-com, hotukdeals-com, mydealz-de, ozbargain-com-au. Default: the country's order. Example: `[]`
- `include_expired` (boolean): Also return codes a provider marks expired or whose expiry date has passed. Example: `false`
- `resolve_stores` (boolean): When a guessed slug misses on promocodes-com or coupons-com, spend one search_stores call to find the store's slug. Billed even when it finds nothing. Example: `false`
- `max_credits` (number): Most provider credits the whole call may spend. A provider is started only while its price still fits. Example: `25`

Response schema example:
```json
{
  "status": "<status>",
  "store": {},
  "coupons": [],
  "tried": [],
  "summary": {},
  "providerCredits": 0,
  "maxCredits": 0,
  "billingComplete": false,
  "billingNotice": "<billingNotice>",
  "observed_at": "<observed_at>"
}
```
