# Performance — Eto API

> Each listing over time, the price that sold best, side-by-side comparisons with the chance each listing is truly best, and saved A/B tests.

Base URL `https://eto.tools/api/v1/`. Every request carries the `X-Eto-API-Key` header. Part of the [Eto API reference](https://eto.tools/dev/docs/).

## Endpoints in this category

- [GET /api/v1/performance/{shop_id}/listings/{listing_id}](https://eto.tools/dev/docs/performance/listing-performance.md): One listing over time, and which price sold best
- [GET /api/v1/performance/compare](https://eto.tools/dev/docs/performance/listing-compare.md): Compare 2 to 25 listings, with the chance each is truly best
- [GET /api/v1/performance/{shop_id}/changes](https://eto.tools/dev/docs/performance/listing-changes.md): Price, photo, title and tag changes, with units a day before and after
- [GET /api/v1/performance/tests](https://eto.tools/dev/docs/performance/ab-tests.md): Your saved A/B tests
- [GET /api/v1/performance/tests/{test_id}](https://eto.tools/dev/docs/performance/ab-test-detail.md): One A/B test and who is winning

## GET /api/v1/performance/{shop_id}/listings/{listing_id}

One listing over time, and which price sold best

- Operation ID: `listing_performance`
- Slug: `listing-performance`
- Category: Performance
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-listing-performance
- Markdown: https://eto.tools/dev/docs/performance/listing-performance.md

Everything about one listing for a window: daily (or weekly) views, favourites, units sold, revenue and list price; totals against the window before; every price, photo, title, tag and state change; and sales by price point, price period and variation.

To answer "which price sells best": read listing.sales.periods (each run of one list price with units_per_day and conversion) and listing.sales.best_period_price. Periods from before readings existed are inferred from the prices buyers paid (source="sales").

━━━ HOW THE NUMBERS ARE MADE ━━━

Every listing on every connected store is read every six hours (00:05, 06:05, 12:05, 18:05 UTC). Views and favourites are GAINS per day in your timezone (Etsy reports lifetime counters and tallies views once a day, so today's views are null until tomorrow). Units and revenue come from your synced orders at the price buyers actually paid; cancelled and fully refunded orders do not count. Conversion = units sold / views gained, only over days whose views are known. Money is integer cents in the listing's currency.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop id. |
| `listing_id` | path | `integer` | yes | The Etsy listing id. |
| `period` | query | `string` | no | The window. Or pass start_date and end_date instead. Default: `30d`. One of: `24h`, `7d`, `30d`, `90d`, `1y`, `ytd`, `all`. |
| `start_date` | query | `string` | no | YYYY-MM-DD, inclusive. With end_date. |
| `end_date` | query | `string` | no | YYYY-MM-DD, inclusive. With start_date. |
| `grain` | query | `string` | no | Bucket size. auto = daily up to 120 days, then weekly. Default: `auto`. One of: `auto`, `day`, `week`. |

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/performance/53081804/listings/4100000016?period=90d"
```

```python
import requests

url = "https://eto.tools/api/v1/performance/53081804/listings/4100000016?period=90d"
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/performance/53081804/listings/4100000016?period=90d";

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`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-listing-performance) shows the fields it returns.

### 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.


## GET /api/v1/performance/compare

Compare 2 to 25 listings, with the chance each is truly best

- Operation ID: `listing_compare`
- Slug: `listing-compare`
- Category: Performance
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-listing-compare
- Markdown: https://eto.tools/dev/docs/performance/listing-compare.md

Side by side: each listing's series and totals, plus confidence.p_best, the probability it has the highest true conversion (Bayesian, 10,000 simulated draws; also low/high, a 90% range). comparison.verdict.verdict is clear (>=95%), likely (>=80%), close, or not_enough (fewer than 300 views per listing or 5 sales in total). Built for photo and price A/B tests: list the same product several times, then compare.

━━━ HOW THE NUMBERS ARE MADE ━━━

Every listing on every connected store is read every six hours (00:05, 06:05, 12:05, 18:05 UTC). Views and favourites are GAINS per day in your timezone (Etsy reports lifetime counters and tallies views once a day, so today's views are null until tomorrow). Units and revenue come from your synced orders at the price buyers actually paid; cancelled and fully refunded orders do not count. Conversion = units sold / views gained, only over days whose views are known. Money is integer cents in the listing's currency.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `listings` | query | `string` | yes | Comma-separated SHOP_ID:LISTING_ID pairs, 2 to 25. |
| `period` | query | `string` | no | The window. Or pass start_date and end_date instead. Default: `30d`. One of: `24h`, `7d`, `30d`, `90d`, `1y`, `ytd`, `all`. |
| `start_date` | query | `string` | no | YYYY-MM-DD, inclusive. With end_date. |
| `end_date` | query | `string` | no | YYYY-MM-DD, inclusive. With start_date. |
| `align` | query | `string` | no | calendar = same dates for all; launch = day 0 is each listing's own launch. Default: `calendar`. One of: `calendar`, `launch`. |
| `metric` | query | `string` | no | What "best" means: sales per view, or favourites per view (an earlier signal). Default: `conversion`. One of: `conversion`, `favourite_rate`. |

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/performance/compare?listings=53081804:111,53081804:222&period=30d"
```

```python
import requests

url = "https://eto.tools/api/v1/performance/compare?listings=53081804:111,53081804:222&period=30d"
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/performance/compare?listings=53081804:111,53081804:222&period=30d";

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`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-listing-compare) shows the fields it returns.

### 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.


## GET /api/v1/performance/{shop_id}/changes

Price, photo, title and tag changes, with units a day before and after

- Operation ID: `listing_changes`
- Slug: `listing-changes`
- Category: Performance
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-listing-changes
- Markdown: https://eto.tools/dev/docs/performance/listing-changes.md

Every change Eto noticed between six-hour readings, newest first, with impact: units a day in the 14 days before and after. Price and state changes carry old and new values; photo, title and tag changes only say that they happened (no content is stored).

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop id. |
| `period` | query | `string` | no | The window. Or pass start_date and end_date instead. Default: `30d`. One of: `24h`, `7d`, `30d`, `90d`, `1y`, `ytd`, `all`. |
| `start_date` | query | `string` | no | YYYY-MM-DD, inclusive. With end_date. |
| `end_date` | query | `string` | no | YYYY-MM-DD, inclusive. With start_date. |
| `kinds` | query | `string` | no | Comma-separated: price, photo, title, tags, state. |

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/performance/53081804/changes?kinds=price"
```

```python
import requests

url = "https://eto.tools/api/v1/performance/53081804/changes?kinds=price"
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/performance/53081804/changes?kinds=price";

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`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-listing-changes) shows the fields it returns.

### 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.


## GET /api/v1/performance/tests

Your saved A/B tests

- Operation ID: `ab_tests`
- Slug: `ab-tests`
- Category: Performance
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-ab-tests
- Markdown: https://eto.tools/dev/docs/performance/ab-tests.md

The A/B tests saved on Analytics > Performance > Tests: name, start and end, size.

### Parameters

None. Send the request with only the API key header.

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/performance/tests"
```

```python
import requests

url = "https://eto.tools/api/v1/performance/tests"
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/performance/tests";

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`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-ab-tests) shows the fields it returns.

### 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.


## GET /api/v1/performance/tests/{test_id}

One A/B test and who is winning

- Operation ID: `ab_test_detail`
- Slug: `ab-test-detail`
- Category: Performance
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-ab-test-detail
- Markdown: https://eto.tools/dev/docs/performance/ab-test-detail.md

The test (with each listing's label, e.g. "Photo B") and the same comparison as listing_compare, lined up from the day the test started.

━━━ HOW THE NUMBERS ARE MADE ━━━

Every listing on every connected store is read every six hours (00:05, 06:05, 12:05, 18:05 UTC). Views and favourites are GAINS per day in your timezone (Etsy reports lifetime counters and tallies views once a day, so today's views are null until tomorrow). Units and revenue come from your synced orders at the price buyers actually paid; cancelled and fully refunded orders do not count. Conversion = units sold / views gained, only over days whose views are known. Money is integer cents in the listing's currency.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `test_id` | path | `integer` | yes | From ab_tests. |
| `period` | query | `string` | no | The window. Or pass start_date and end_date instead. Default: `30d`. One of: `24h`, `7d`, `30d`, `90d`, `1y`, `ytd`, `all`. |
| `start_date` | query | `string` | no | YYYY-MM-DD, inclusive. With end_date. |
| `end_date` | query | `string` | no | YYYY-MM-DD, inclusive. With start_date. |

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/performance/tests/12"
```

```python
import requests

url = "https://eto.tools/api/v1/performance/tests/12"
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/performance/tests/12";

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`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-ab-test-detail) shows the fields it returns.

### 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.