# List ads

Read observed Zepto advertising placements for home, search or category contexts at a selected delivery context.

- Platform: [Zepto](https://docs.upscrape.com/docs/platforms/zepto)
- Capability ID: `zepto.ads`
- Cost: 1 credit per request
- Maximum runtime: 180 seconds
- Execute endpoint: `POST https://data.upscrape.com/execute`

## Request

Use the exact public capability ID in the shared execute envelope.

```bash
curl --request POST \
  --url https://data.upscrape.com/execute \
  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: wait=30" \
  --data '{
  "input": {
    "latitude": 12.96902,
    "limit": 5,
    "longitude": 77.75395,
    "page_type": "HOME"
  },
  "capability": "zepto.ads"
}'
```

## Input

page_type is HOME, SEARCH or CATEGORY and defaults to HOME. For SEARCH provide the query or a supported search page URL. For CATEGORY provide category/subcategory identity or a supported category context.

For location-specific placements, provide store_id, a six-digit pincode, or both latitude and longitude. limit accepts 1 to 100 placements.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `category_id` | `string` | No | Category ID (relevant when page_type is CATEGORY). |
| `latitude` | `number` | No | Latitude for location-based store resolution. From -90 to 90. |
| `limit` | `integer` | No | Maximum number of ad placements to return. From 1 to 100. Default: `20`. |
| `longitude` | `number` | No | Longitude for location-based store resolution. From -180 to 180. |
| `page_type` | `string` | No | Type of page to fetch ads for. Allowed values: `HOME`, `SEARCH`, `CATEGORY`. Default: `HOME`. |
| `pincode` | `string` | No | Six-digit Indian pincode. When provided, Upscrape resolves coordinates and the Zepto delivery store automatically. |
| `query` | `string` | No | Search query (relevant when page_type is SEARCH). |
| `store_id` | `string` | No | Zepto store ID. Defaults to the public Bangalore sample store. |
| `subcategory_id` | `string` | No | Subcategory ID (relevant when page_type is CATEGORY). |
| `url` | `string` | No | Direct URL to a Zepto page for ad context. |

### Example input

```json
{
  "latitude": 12.96902,
  "limit": 5,
  "longitude": 77.75395,
  "page_type": "HOME"
}
```

## Response

Successful output is returned in `results[0].data`.

Returned placement rows can include product, page, widget, rank, sponsorship, campaign and tracking fields. Treat them as observed placement metadata for that request.

campaign_name, ads_response_id, ucl_id and placement/container identifiers do not establish globally unique campaigns, lifetime or complete advertising coverage.

An explicitly empty terminal SEARCH layout can return zero results. Do not generalize that empty-result rule to HOME or CATEGORY without corresponding evidence.

### Illustrative sample output

This example shows one response. Values and optional fields vary with the data available.

```json
{
  "captured_at": "2026-09-24T09:55:30.754879767Z",
  "count": 3,
  "location": {
    "eta_minutes": 6,
    "eta_serviceable": true,
    "latitude": 12.96902,
    "longitude": 77.75395,
    "secondary_store_ids": [
      "0059ff6a-7eb0-477a-a7f5-69256f2c444b"
    ],
    "serviceable": true,
    "store_id": "b4dc8d65-ed2e-4142-81b6-373982b13500",
    "store_ids": [
      "b4dc8d65-ed2e-4142-81b6-373982b13500",
      "0059ff6a-7eb0-477a-a7f5-69256f2c444b"
    ]
  },
  "page_type": "HOME",
  "results": [
    {
      "element_id": "422c1cbe-a5b5-4118-9c6b-f7c6251fced3",
      "element_name": "Everyday lowest price",
      "element_position_inside_widget": 1,
      "element_type": "BANNER",
      "image_url": "https://cdn.zeptonow.com/production/tr:w-600,ar-1000-1000,pr-true,f-auto,q-80/inventory/banner/601180a6-b82f-499b-a24f-c079904e9f53.png",
      "page_type": "HOME",
      "placement_type": "banner",
      "position_in_list": 1,
      "rank": 1,
      "widget_id": "100000357",
      "widget_name": "WEB_PAAN_OLSX",
      "widget_position": 80,
      "widget_type": "BANNER_GRID"
    },
    {
      "deeplink_url": "https://www.zepto.com/cn/paan-corner/cigarettes/cid/cd50825e-baf8-47fe-9abc-ed9556122a9a/scid/5bcbee47-7c83-4279-80f0-7ecc068496df",
      "element_id": "bad6912d-f8a8-4fa6-9bd7-b5cc63a521ef",
      "element_name": "Paan",
      "element_position_inside_widget": 2,
      "element_type": "BANNER",
      "image_url": "https://cdn.zeptonow.com/production/tr:w-600,ar-1000-1000,pr-true,f-auto,q-80/inventory/banner/85b9411e-fa0e-427f-96ec-97fd4d13aaed.png",
      "page_type": "HOME",
      "placement_type": "banner",
      "position_in_list": 2,
      "rank": 2,
      "widget_id": "100000357",
      "widget_name": "WEB_PAAN_OLSX",
      "widget_position": 80,
      "widget_type": "BANNER_GRID"
    },
    {
      "discount_amount_paise": 3600,
      "is_sponsored": true,
      "discounted_selling_price_paise": 22400,
      "element_position_inside_widget": 1,
      "element_id": "8f5eb151-9e1a-5f53-a171-299f6f539d9e",
      "items_left": 6,
      "store_product_id": "8f5eb151-9e1a-5f53-a171-299f6f539d9e",
      "primary_category_name": "Cleaning Essentials",
      "element_type": "PRODUCT",
      "product_name": "Rin Matic Top Load Detergent Liquid | Pouch",
      "discount_percent": 13,
      "widget_name": "Laundry_Care_HORIZONTAL_LIST",
      "campaign_name": "bachat",
      "mrp_paise": 26000,
      "primary_subcategory_name": "Liquid Detergents & Additives",
      "category_id": "1a7e46a8-e627-450f-8960-490b550eeee6",
      "rank": 3,
      "brand": "Rin",
      "formatted_pack_size": "1 pack (2 kg)",
      "widget_id": "24238",
      "image_url": "https://cdn.zeptonow.com/production/tr:w-600,ar-1000-1000,pr-true,f-auto,q-80/cms/product_variant/aecbb7fc-7f33-46a8-9329-7b5b952bb9a8.jpg",
      "product_variant_id": "5f54bb83-f3e0-4d8d-89b0-6339f3312089",
      "store_id": "b4dc8d65-ed2e-4142-81b6-373982b13500",
      "placement_type": "sponsored_product",
      "primary_subcategory_id": "dfb37880-b40f-4783-9502-a56e12edbabc",
      "product_id": "4ad95205-6122-41b2-b5af-f18f187f924b",
      "selling_price_paise": 22400,
      "page_type": "HOME",
      "product_url": "https://www.zepto.com/pn/rin-matic-top-load-detergent-liquid-pouch/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089",
      "widget_type": "HORIZONTAL_LIST",
      "widget_position": 270,
      "pricing_campaigns": [
        {
          "price_paise": 22400,
          "type": "SUPER_SAVER"
        }
      ],
      "position_in_list": 1
    }
  ]
}
```
### Illustrative output fields

Derived from the sample above for orientation only. These fields are not a fixed response schema.

| Path | Observed type | Example |
| --- | --- | --- |
| `captured_at` | `string` | 2026-09-24T09:55:30.754879767Z |
| `count` | `integer` | 3 |
| `location` | `object` | 8 fields |
| `location.eta_minutes` | `integer` | 6 |
| `location.eta_serviceable` | `boolean` | true |
| `location.latitude` | `number` | 12.96902 |
| `location.longitude` | `number` | 77.75395 |
| `location.secondary_store_ids` | `array` | 1 items |
| `location.serviceable` | `boolean` | true |
| `location.store_id` | `string` | b4dc8d65-ed2e-4142-81b6-373982b13500 |
| `location.store_ids` | `array` | 2 items |
| `page_type` | `string` | HOME |
| `results` | `array` | 3 items |
| `results` | `array` | 3 items |

## Execution behavior

A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job.

## Related documentation

- [Authentication](https://docs.upscrape.com/docs/api/authentication)
- [Jobs and results](https://docs.upscrape.com/docs/api/jobs)
- [Errors and retries](https://docs.upscrape.com/docs/api/errors)
- [Idempotency](https://docs.upscrape.com/docs/api/idempotency)