> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sales history

> Estimated sales and revenue for every completed month of a product or shop.

`GET /v1/research/products/{id}/history` and `GET /v1/research/shops/{id}/history` return every completed calendar month (UTC) of estimated sales and revenue in one response. This one prints a product's months:

<CodeGroup>
  ```bash cURL theme={null}
  curl --fail-with-body -sS https://api.alura.io/v1/research/products/4524717183/history \
    -H "Authorization: Bearer $ALURA_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  interface History {
    history_through: string;
    methodology_version: string;
    data: { month: string; est_sales: number | null; est_revenue_usd: number | null; reviews: number | null }[];
  }

  const res = await fetch('https://api.alura.io/v1/research/products/4524717183/history', {
    headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}` },
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  const history = (await res.json()) as History;

  console.log(`through ${history.history_through}, methodology ${history.methodology_version}`);
  for (const m of history.data) {
    // A month Alura has no data for is null, never 0.
    console.log(m.est_sales === null ? `${m.month}: unknown` : `${m.month}: ${m.est_sales} sales, ${m.est_revenue_usd ?? 'unknown'} USD`);
  }
  ```

  ```python Python theme={null}
  import json
  import os
  import urllib.request

  request = urllib.request.Request(
      "https://api.alura.io/v1/research/products/4524717183/history",
      headers={"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}"},
  )
  with urllib.request.urlopen(request) as response:
      history = json.load(response)

  print(f"through {history['history_through']}, methodology {history['methodology_version']}")
  for m in history["data"]:
      # A month Alura has no data for is null, never 0.
      if m["est_sales"] is None:
          print(f"{m['month']}: unknown")
      else:
          revenue = "unknown" if m["est_revenue_usd"] is None else m["est_revenue_usd"]
          print(f"{m['month']}: {m['est_sales']} sales, {revenue} USD")
  ```
</CodeGroup>

The response looks like this:

```json theme={null}
{
  "object": "research.history",
  "resource": { "object": "research.product", "id": "4524717183" },
  "granularity": "month",
  "history_through": "2026-09",
  "methodology_version": "2026-10",
  "methodology_url": "https://docs.alura.io/methodology/sales-estimates",
  "data": [
    { "month": "2026-07", "est_sales": 214, "est_revenue_usd": 5799, "reviews": 19 },
    { "month": "2026-08", "est_sales": null, "est_revenue_usd": null, "reviews": null },
    { "month": "2026-09", "est_sales": 236, "est_revenue_usd": 6396, "reviews": 21 }
  ],
  "as_of": "2026-10-13T09:30:00Z"
}
```

* Months run up to `history_through`, the last completed month. The current month is never included, because it isn't over.
* A month Alura has no data for is `null`, not `0`. `data` itself is `null` when Alura has no usable history for the item, so check it before looping.
* `est_revenue_usd` values each month's sales at the product's **current** price, not the price it had that month. For a shop it uses the shop's current average price.
* Estimates for recent months can still change, because buyers keep reviewing orders for weeks. `methodology_version` says which method produced the numbers; see [Sales estimates](/methodology/sales-estimates).

Sales history needs the Growth plan or above. On Free and Basic, the answer is `403 plan_required` with `upgrade_url`, and nothing is charged.

`GET /v1/research/products/{id}/history` costs 1 API credit for the whole history, as does `GET /v1/research/shops/{id}/history`. In an AI assistant, the `get_sales_history` tool covers both. History never fetches anything from Etsy: an item Alura doesn't know answers `404 not_found`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.