# Instamart product search API reference

Last updated 7 Nov 2026.

GET /v1/data/search-ranks with retailer=instamart returns one record per product, search term, pin code and day Rewalto searched Swiggy Instamart: the best place the product held in the results, its page and slot, and how often it was seen, in the top ten and marked sponsored. Rewalto holds about 2,69,862 Instamart search rank records, for days from 26 Sept 2026 to 7 Nov 2026. It needs an API key and costs 1 credit per 10 readings; the sample record below is free.

## Key facts

| | |
| --- | --- |
| Endpoint | GET /v1/data/search-ranks |
| App filter | retailer=instamart |
| Cost | 1 credit per 10 readings (Only delivered records use credits) |
| Key | API key needed |
| Records held | about 2,69,862, 26 Sept 2026 to 7 Nov 2026 (From the coverage matrix) |

## Request

GET https://api.rewalto.com/v1/data/search-ranks, with an API key sent as Authorization: Bearer. For one retailer: on each IST day, for each search term and pin code (or national) Rewalto searched, where each listing ranked: its best place in the whole result list (ads included; null where the reply does not state where its page starts, beyond the first page), the first page and slot it was seen at, and how many replies showed it, placed it in places 1 to 10 and marked it sponsored. Observed, never a model. Newest day first, optionally one product (retailerSku), one search term, one pin code and a day range. Catalogue entries qc_rank_history and mp_rank_history; one record is one listing, term, pin and day. Charged per record delivered at the dataset’s published rate (GET /v1/catalogue/entries/{id} shows it); re-reading the same records within 7 days is free, and an empty page costs nothing. No quote is needed: meta.credits shows the rate charged and the credits left. When the credits cannot cover the page: 402 credits_exhausted and no data.

cURL:

```bash
curl -H "Authorization: Bearer $REWALTO_API_KEY" \
  "https://api.rewalto.com/v1/data/search-ranks?retailer=instamart&searchTerm=amul%20taaza%20milk&pincode=400001&limit=20"
```

## Parameters

| Name | In | Required | Type | What it means | Example |
| --- | --- | --- | --- | --- | --- |
| `retailer` | query | yes | string | The retailer (a key from /v1/data/retailers). Use instamart for Instamart. | `"blinkit"` |
| `retailerSku` | query | no | string | Only this product (the retailer’s own id). | `"sku-123"` |
| `searchTerm` | query | no | string | Only this search term (exact). | `"shampoo"` |
| `pincode` | query | no | string | Only this six-digit pin code, or national. | `"560034"` |
| `from` | query | no | string | Only IST days on or after this day (YYYY-MM-DD). | `"2026-10-01"` |
| `to` | query | no | string | Only IST days on or before this day (YYYY-MM-DD). | `"2026-10-17"` |
| `limit` | query | no | string | How many records to return, 1 to 500. Default 100. | `"100"` |
| `cursor` | query | no | string | The nextCursor of the previous page, sent back with exactly the same filters. A cursor from other filters is refused. | `"eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"` |

## Record fields

| Field | Type | What it means | Example |
| --- | --- | --- | --- |
| `day` | string (date) | The IST day. | `"2026-10-21"` |
| `retailer` | string | The retailer. | `"flipkart"` |
| `searchTerm` | string | The search term. | `"instant coffee"` |
| `pincode` | string | The pin code searched at, or national. | `"national"` |
| `retailerSku` | string | The retailer’s own product id. | `"COFG5Z7H2ZQ8YH5K"` |
| `brand` | string | The brand on the card; empty when it named none. | `"Nescafe"` |
| `bestPlace` | null or integer | Best position in the whole result list that day (1 is first). | `3` |
| `bestPage` | integer | The first result page it was seen on (1 is the first page). | `1` |
| `bestPageSlot` | integer | Its best position on that page, ads included. | `3` |
| `readings` | integer | Search replies that showed it that day. | `4` |
| `top10Readings` | integer | Of those, replies that placed it in places 1 to 10. | `4` |
| `adAwareReadings` | integer | Replies from a reading that can see the ad marker. | `4` |
| `sponsoredReadings` | integer | Of the ad-aware replies, those that marked it sponsored. | `0` |
| `firstSeen` | string (date-time) | The first reading that day. | `"2026-10-21T02:31:10.000000Z"` |
| `lastSeen` | string (date-time) | The last reading that day. | `"2026-10-21T14:02:44.000000Z"` |

## Errors

Errors share one shape: error.code, a retry advice and a request id.

| Status | error.code |
| --- | --- |
| 400 | `invalid_request` |
| 401 | `key_expired, key_revoked, session_expired, unauthenticated` |
| 402 | `credits_exhausted, plan_required` |
| 403 | `org_missing, scope_missing` |
| 409 | `not_for_sale` |
| 429 | `rate_limited` |
| 500 | `internal` |
| 503 | `unavailable` |

- [What to do for each error](https://rewalto.com/developers/docs/errors)

## Credit cost

1 credit per 10 readings. Every account gets 1,000 free credits a month, and a read that delivers nothing costs nothing.

## A real Instamart record

One record from the free samples route (GET /v1/data/samples?dataset=search_rank), exactly as the paid read returns it, with long lists cut to three items. Samples are at least a week old; this set holds records up to 2 Nov 2026.

```json
{
  "day": "2026-11-02",
  "retailer": "instamart",
  "searchTerm": "amul taaza milk",
  "pincode": "400001",
  "retailerSku": "BQ5YQH8TEN",
  "brand": "Amul",
  "bestPlace": 1,
  "bestPage": 1,
  "bestPageSlot": 1,
  "readings": 1,
  "top10Readings": 1,
  "adAwareReadings": 0,
  "sponsoredReadings": 0,
  "firstSeen": "2026-11-01T21:13:01.000000Z",
  "lastSeen": "2026-11-01T21:13:01.000000Z"
}
```

## Related

- [Instamart product search API overview](https://rewalto.com/developers/api/instamart/search)
- [Instamart API documentation](https://rewalto.com/developers/docs/api/instamart)
- [Full API contract (OpenAPI)](https://rewalto.com/developers/openapi.json)
- [Data catalogue for agents](https://rewalto.com/developers/catalog.json)
- [MCP server tools](https://rewalto.com/developers/mcp)
- [Quickstart: your first request](https://rewalto.com/developers/docs/quickstart)
- [Pricing and free credits](https://rewalto.com/pricing)

---

Canonical page: https://rewalto.com/developers/docs/api/instamart/search
Last content change: 2026-11-07