# Batch get listings

> Eto API reference for `GET /api/v1/listings/batch`. Base URL `https://eto.tools/api/v1/`. Authenticate with the `X-Eto-API-Key` header.

Part of the [Eto API reference](https://eto.tools/dev/docs/). The full reference in one file is at [llms-full.txt](https://eto.tools/dev/docs/llms-full.txt); the machine-readable schema is at [openapi.json](https://eto.tools/dev/docs/openapi.json).

## GET /api/v1/listings/batch

Batch get listings

- Operation ID: `listings_batch`
- Slug: `listings-batch`
- Category: Listings
- Authentication: API key only. Reads public marketplace data, so no store needs to be connected.
- HTML: https://eto.tools/dev/docs/#ep-listings-batch
- Markdown: https://eto.tools/dev/docs/listings/listings-batch.md

Retrieve up to 100 listings in a single request. API key only: no store needs to be connected.
With includes=BuyerPrice and buyer_country (e.g. GB), each listing carries buyer_price: the buyer-facing price with VAT, UK inclusive shipping and any active promotion. Etsy only returns buyer_price on this route.

Proxied to the Etsy API at `/v3/application/listings/batch`. Fields Etsy returns are passed through untouched.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `listing_ids` | query | `string` | yes | Comma-separated listing IDs (max 100) |
| `includes` | query | `string` | no | Comma-separated associations: Shop, Images, User, Translations, Videos, Personalization, BuyerPrice |
| `buyer_country` | query | `string` | no | ISO 3166-1 alpha-2 country (e.g. GB, DE) for buyer_price. Required with includes=BuyerPrice. Does not filter listings. |
| `currency` | query | `string` | no | ISO 4217 currency (e.g. EUR) to add converted_price to each listing. |
| `legacy` | query | `boolean` | no | Enable the newer processing-profile fields. |

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/batch?listing_ids=123,456,789&includes=BuyerPrice&buyer_country=GB"
```

```python
import requests

url = "https://eto.tools/api/v1/listings/batch?listing_ids=123,456,789&includes=BuyerPrice&buyer_country=GB"
headers = {"X-Eto-API-Key": "eto_your_key"}

response = requests.get(url, headers=headers, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/listings/batch?listing_ids=123,456,789&includes=BuyerPrice&buyer_country=GB";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-Eto-API-Key": "eto_your_key",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`, passed through from Etsy’s `/v3/application/listings/batch` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.