# Quickstart: your first okdata call

> Get a key, make one call to Xiaohongshu note search, read the data and the bill, then fetch the next page. About two minutes.

Canonical page: https://okdata.online/docs/quickstart/

## 1. Get a key

Keys start with `okd_`. Self-serve signup is not open yet: write to hello@okdata.online and we will send you one. Keep it in an environment variable, never in code:

```bash
export OKDATA_API_KEY="okd_..."
```

## 2. Look before you pay

The status route is free and needs no key. It tells you which endpoints are up right now:

```bash
curl https://api.okdata.online/v1/catalog/status
```

## 3. Make one call

Search Xiaohongshu notes for a keyword. The path is the endpoint id with dots turned into slashes:

```bash
curl -G "https://api.okdata.online/v1/xiaohongshu/notes/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=sunscreen'
```

That is one call. It costs $0.02 and returns a page of about 20 notes.

## 4. Read the answer

```json
{
  "code": "ok",
  "data": { "items": [ { "id": "6731f0a2000000001b02c3d4", "type": "image", "title": "...", "metrics": { "likes": 48200, "views": null } } ] },
  "page": { "next_cursor": "eyJvIjoyMH0", "has_more": true },
  "meta": {
    "billing": { "amount": "0.018", "currency": "USD", "balance_after": "9.982" },
    "unavailable": { "metrics.views": "platform" }
  }
}
```

- `data.items` holds the notes. Every platform answers with the same [Post](/docs/objects/post/) shape.
- `meta.billing.amount` is what this call cost, in US dollars.
- `meta.unavailable` names fields that are null and why. Xiaohongshu does not show view counts, so `metrics.views` is null with the reason `platform`.

## 5. Get the next page

Send `page.next_cursor` back as `cursor`. Each page is a separate call with its own price; stop when you have enough or when `page.has_more` is false.

```bash
curl -G "https://api.okdata.online/v1/xiaohongshu/notes/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=sunscreen' \
  --data-urlencode 'cursor=eyJvIjoyMH0'
```

## 6. When a call fails

You get one error shape with `code`, `message`, `charged` and `retry`. Failed calls are not charged. A timeout says `charged: null`; resend it with the same `Idempotency-Key` and it can never be billed twice. Every code is on the [errors page](/docs/errors/).

## Next

- Give an AI agent the same data over [MCP](/mcp/).
- Browse [all 35 endpoints](/apis/) and their prices.
- Read how [requests, paging, view and fields](/docs/requests/) work.