# Instacart API

> Instacart returns grocery products, prices, and stock estimates, available as a workflow and API.

Instacart searches guest-visible grocery products at a named store using a product query and five-digit US delivery ZIP code. Search products returns product names, brands, sizes, prices, and stock estimates for that search.

- Page: https://fous.com/tools/instacart
- Handle: `@instacart`
- Category: [Commerce](https://fous.com/tools/category/commerce)
- Source website: https://instacart.com
- Last verified: Sep 29, 2026

## Methods

### Search products

Operation `search_products`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Search a named Instacart store's guest-visible grocery products for a US ZIP code. Prices are in USD and can differ from in-store prices; stock estimates can change.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `query` | string | yes | `"eggs"` | The grocery product to search for, for example oat milk. |
| `store` | string | yes | `"Costco"` | Store name, for example Safeway or Costco. |
| `zip_code` | string | yes | `"10001"` | Five-digit US delivery ZIP code, for example 94103. |
| `max_results` | integer | no | `5` | Most products to return, for example 20. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query",
    "zip_code",
    "store"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "The grocery product to search for, for example oat milk.",
      "examples": [
        "eggs",
        "oat milk"
      ]
    },
    "store": {
      "type": "string",
      "minLength": 1,
      "description": "Store name, for example Safeway or Costco.",
      "examples": [
        "Costco",
        "Safeway"
      ]
    },
    "zip_code": {
      "type": "string",
      "pattern": "^[0-9]{5}$",
      "description": "Five-digit US delivery ZIP code, for example 94103.",
      "examples": [
        "10001",
        "94103"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 60,
      "minimum": 1,
      "description": "Most products to return, for example 20.",
      "x-fous-developer": true,
      "examples": [
        5
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "query": "eggs",
      "store": "Costco",
      "zip_code": "10001",
      "max_results": 5
    },
    {
      "query": "oat milk",
      "store": "Safeway",
      "zip_code": "94103"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `store` | string | `"Costco"` | Store used for the search. |
| `products` | array |  |  |
| `products[].size` | string or null | `"each"` |  |
| `products[].brand` | string or null | `"Kirkland Signature"` |  |
| `products[].price` | number or null | `10.31` |  |
| `products[].currency` | string | `"USD"` |  |
| `products[].in_stock` | boolean | `true` |  |
| `products[].image_link` | string or null | `"https://d2lnr5mha7bycj.cloudfront.net/product-image/file/large_a465d2c7-6689-46db-8c13-ab57499de74f.jpg"` |  |
| `products[].unit_price` | string or null | `"$0.43/ct"` |  |
| `products[].product_link` | string | `"https://www.instacart.com/products/19232685-kirkland-signature-organic-free-range-egg-usda-grade-a-lg-24-ct-24-ct?retai` |  |
| `products[].product_name` | string | `"Kirkland Signature Free-Range Organic Eggs, Large, 24-count"` |  |
| `products[].original_price` | number or null | `5.99` |  |

**Example input**

```json
{
  "query": "eggs",
  "store": "Costco",
  "zip_code": "10001",
  "max_results": 5
}
```

**Example output**

```json
{
  "store": "Costco",
  "products": [
    {
      "size": "each",
      "brand": "Kirkland Signature",
      "price": 10.31,
      "currency": "USD",
      "in_stock": true,
      "image_link": "https://d2lnr5mha7bycj.cloudfront.net/product-image/file/large_a465d2c7-6689-46db-8c13-ab57499de74f.jpg",
      "unit_price": "$0.43/ct",
      "product_link": "https://www.instacart.com/products/19232685-kirkland-signature-organic-free-range-egg-usda-grade-a-lg-24-ct-24-ct?retailerSlug=costco",
      "product_name": "Kirkland Signature Free-Range Organic Eggs, Large, 24-count",
      "original_price": null
    },
    {
      "size": "each",
      "brand": "Kirkland Signature",
      "price": 4.71,
      "currency": "USD",
      "in_stock": true,
      "image_link": "https://d2lnr5mha7bycj.cloudfront.net/product-image/file/large_cf27eeda-d364-4b40-b2b2-9b1837ef51e3.jpg",
      "unit_price": null,
      "product_link": "https://www.instacart.com/products/3308878-kirkland-signature-cage-free-eggs-24-ct-24-ct?retailerSlug=costco",
      "product_name": "Kirkland Signature Eggs, Large, 24-count",
      "original_price": null
    },
    {
      "size": "each",
      "brand": "Kirkland Signature",
      "price": 17.4,
      "currency": "USD",
      "in_stock": true,
      "image_link": "https://d2lnr5mha7bycj.cloudfront.net/product-image/file/large_ba13714d-b48d-4901-a35b-97b8f96c609e.jpg",
      "unit_price": "$4.35 each",
      "product_link": "https://www.instacart.com/products/24518529-kirkland-signature-peeled-ready-to-eat-organic-hard-boiled-eggs-2-ct?retailerSlug=costco",
      "product_name": "Kirkland Signature Organic Hard-Boiled Eggs, Cage Free, Peeled, 16-count, 2-pack",
      "original_price": null
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@instacart",
  "visibility": "public",
  "operation": "search_products",
  "version": 1,
  "input": {
    "query": "eggs",
    "store": "Costco",
    "zip_code": "10001",
    "max_results": 5
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@instacart\",\n  \"visibility\": \"public\",\n  \"operation\": \"search_products\",\n  \"version\": 1,\n  \"input\": {\n    \"query\": \"eggs\",\n    \"store\": \"Costco\",\n    \"zip_code\": \"10001\",\n    \"max_results\": 5\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@instacart",
  "visibility": "public",
  "operation": "search_products",
  "version": 1,
  "input": {
    "query": "eggs",
    "store": "Costco",
    "zip_code": "10001",
    "max_results": 5
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/instacart`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `search_products`: Search products. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-instacart https://api.fous.com/mcp/tools/instacart --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Compare grocery prices across named stores.
- Check estimated product availability for a delivery ZIP code.
- Find product sizes and brands for a grocery query.
- Review product links and images for shopping research.

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Instacart tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Instacart account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from instacart.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What does a grocery product cost at a store?

Search products returns product prices in USD for the named store and ZIP code; prices can differ from in-store prices.

### Is a grocery product estimated to be in stock?

Search products returns stock estimates for matching products, which can change.

### Which brands and sizes match a grocery search?

Search products returns matching product brands and sizes for the query, store, and ZIP code.

## Related

- [Walmart API](https://fous.com/tools/walmart.md): Walmart helps shoppers find products from Walmart and marketplace sellers, view details, prices, ratings and reviews; availability uses Walmart’s default location, not ZIP codes.
- [Costco API](https://fous.com/tools/costco.md): Costco returns US product prices/details and warehouse hours/services/gas prices; delivery affects availability, member prices may be hidden, and posted gas and holiday hours may differ.
- [Aldi API](https://fous.com/tools/aldi.md): Search groceries and prices at ALDI US.
- [Trader Joe's API](https://fous.com/tools/trader-joes.md): Trader Joe's groceries, beverages, flowers, plants, and other products.
- [Nordstrom API](https://fous.com/tools/nordstrom.md): Search clothing, shoes, and beauty products at Nordstrom.
- [Tesco API](https://fous.com/tools/tesco.md): Search Tesco groceries, prices, and promotions.
- [Target API](https://fous.com/tools/target.md): Target helps shoppers find products, details, photos, ratings, links, current prices, and nearby-store stock and pickup or delivery availability; prices and availability can change by location and time.
- [Macy's API](https://fous.com/tools/macys.md): Shop Macy's products and sales.
- [All Commerce tools](https://fous.com/tools/category/commerce)