# Quickstart

Create a key, list the trends about France, then plug the same data into your AI assistant. It takes about five minutes.

You need an EarlyWave account on a plan that includes the API (Pro or Max, see [plans](https://www.earlywave.ai/pricing)).

## 1. Create a key

1. Open EarlyWave › **Settings › API & MCP** ([open it](https://www.earlywave.ai/settings/developers)).
2. Create a key and give it a name you will recognise later, such as `laptop` or `slack-bot`.
3. Pick its scopes: `rest` for the REST API, `mcp` for the MCP server, or both.
4. Copy the key. It starts with `ew_live_` and is shown only once.

Keep it in an environment variable rather than in your code:

```bash
export EARLYWAVE_API_KEY="ew_live_..."
```

## 2. Make a first request

List the three strongest stories about France right now:

```bash
curl "https://api.earlywave.ai/api/v1/trends?country=FR&limit=3" \
  -H "Authorization: Bearer $EARLYWAVE_API_KEY"
```

The answer is a page of trends (shortened here to one):

```json
{
  "trends": [
    {
      "id": 48213,
      "title": "Rail strike disrupts travel across France",
      "url": "https://www.earlywave.ai/trends/trend/48213",
      "status": "active",
      "stage": "accelerating",
      "category": "society",
      "reach": "national",
      "subject_countries": ["FR"],
      "publisher_countries": ["FR", "BE", "CH"],
      "item_count": 142,
      "source_count": 61,
      "signal_score": 74.2,
      "velocity_1h": 9,
      "velocity_24h": 118,
      "started_at": "2026-10-18T05:42:00.000Z",
      "earliest_item_at": "2026-10-18T05:42:00.000Z",
      "first_seen_at": "2026-10-18T06:10:12.000Z",
      "last_activity_at": "2026-10-19T08:55:31.000Z"
    }
  ],
  "total": 37,
  "limit": 3,
  "offset": 0,
  "has_more": true
}
```

`has_more` is `true`: ask for the next page with `offset=3`. Every response also carries `X-RateLimit-Remaining` and an `X-Request-Id`.

Open one trend, then see where it is covered:

```bash
curl "https://api.earlywave.ai/api/v1/trends/48213" \
  -H "Authorization: Bearer $EARLYWAVE_API_KEY"

curl "https://api.earlywave.ai/api/v1/trends/48213/coverage" \
  -H "Authorization: Bearer $EARLYWAVE_API_KEY"
```

The [Trends guide](https://www.earlywave.ai/developers/docs/trends) walks through every filter and field.

### The same request in code

JavaScript (Node 18+, Deno, Bun):

```js
const res = await fetch("https://api.earlywave.ai/api/v1/trends?country=FR&limit=3", {
  headers: { Authorization: `Bearer ${process.env.EARLYWAVE_API_KEY}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
for (const trend of body.trends) console.log(trend.source_count, trend.title);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.earlywave.ai/api/v1/trends",
    params={"country": "FR", "limit": 3},
    headers={"Authorization": f"Bearer {os.environ['EARLYWAVE_API_KEY']}"},
    timeout=30,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
for trend in body["trends"]:
    print(trend["source_count"], trend["title"])
```

## 3. Connect an MCP client

With a key that has the `mcp` scope, add EarlyWave to Claude Code in one line:

```bash
claude mcp add --transport http earlywave https://api.earlywave.ai/mcp \
  --header "Authorization: Bearer YOUR_KEY"
```

Then ask, for example: *"What are the breakout stories about Germany since yesterday, and which countries cover the first one?"* The assistant calls `list_trends` and `get_trend_coverage` for you.

Cursor, VS Code, Claude Desktop and other clients: see [MCP server](https://www.earlywave.ai/developers/docs/mcp).

## Next

- [Authentication](https://www.earlywave.ai/developers/docs/authentication) — scopes, legacy keys, access errors.
- [Errors, limits and paging](https://www.earlywave.ai/developers/docs/errors-and-limits) — what to do with a `429`.
- [API reference](https://www.earlywave.ai/developers/reference) — every operation.

---
Source: https://www.earlywave.ai/developers/docs/quickstart · All docs: https://www.earlywave.ai/llms.txt