# Query the index

Read the settlement record over REST, read-only SQL, or the pre-computed rollups, and know which to reach for.

Section: Get started
Source: https://www.roundhouse.studio/docs/get-started/query-the-index

---

Everything Roundhouse knows is readable. There is no private tier of the dataset; the paid tiers
buy you rate limit and convenience, not access.

Pick a read path by how specific your question is.

| Your question | Use | Cost |
| --- | --- | --- |
| "What is happening right now?" | `GET /v0/flows` | Free |
| "Tell me about this wallet" | `GET /v0/agents/<w>`, `GET /v0/merchants/<w>` | Free |
| "Who sells X?" | `GET /v0/endpoints?q=X` | Free |
| "Show me the payment graph" | `GET /v0/graph` | Free |
| Anything with a `group by` in it | `POST /v0/sql` | Free, rate-limited |
| Natural language, exploratory | [AI playground](https://www.roundhouse.studio/dashboard/playground) | Query Units |

## Fixed endpoints

Free, no key, JSON. The full list with every parameter is the
[API reference](https://www.roundhouse.studio/docs/api); these are the ones you will reach for first.

```http
GET /api/v0/flows?limit=50                    live flow of funds, newest first
GET /api/v0/transactions?limit=50             the global settlement feed
GET /api/v0/agents?q=<search>                 indexed ERC-8004 agents
GET /api/v0/agents/<wallet>                   one agent: identity + settlement stats
GET /api/v0/merchants/<wallet>                one merchant: inbound volume, customers
GET /api/v0/entities/<wallet>/settlements     raw settlements for one wallet
GET /api/v0/endpoints?q=<search>              the priced service directory
GET /api/v0/leaderboard?limit=25              agents ranked by trust
GET /api/v0/facilitators                      who relays payments, and how much
GET /api/v0/graph?days=7                      nodes and payer→payee edges
```

Two paging conventions, and they are not interchangeable:

- **Feeds use a cursor.** `next_before` is an opaque token encoding the whole sort key including
  its tiebreaker. Pass it back as `?before=`. Do not parse it, and do not construct one — a naive
  `block_time` cursor silently drops every row sharing the last row's timestamp, and on a 2-second
  chain most timestamps are shared.
- **The leaderboard uses an offset.** A rank *is* a position, and `score` is nullable, so there is
  nothing stable for a cursor to compare against. `?offset=` in, `next_offset` out.

An empty array is a real answer. A failed read is not: a rejected query returns `503
upstream_unavailable` naming the resource, never `200 {"flows": []}`. On a settlement index "no
rows" reads as "nothing ever happened", which is the one lie the read path is built to prevent.

## Read-only SQL

For everything else. One statement, `SELECT` or `WITH` only, over the public data-layer tables.

```bash
curl -sL -X POST "https://www.roundhouse.studio/api/v0/sql" \
  -H "authorization: Bearer $ROUNDHOUSE_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "sql": "select date_trunc('day', block_time) as day, count(*) as settlements, sum(amount_usd) as usd from settlements where block_time > now() - interval '14 days' group by 1 order by 1 desc"
  }' | jq
```

The sandbox is enforced in the database, not in the request handler: a role that can read only the
public tables, a read-only transaction, an 8-second statement timeout, and a hard 300-row cap.
Write for those limits rather than discovering them — [SQL over the index](https://www.roundhouse.studio/docs/data/sql) has the
readable tables, the useful shapes, and the traps.

## Use the rollups, not the raw table

`settlements` has tens of millions of rows. An unbounded aggregate over it will hit the timeout.
The pre-computed views exist so you do not have to:

| View | Grain | Good for |
| --- | --- | --- |
| `mv_entity_rollups` | one row per wallet | lifetime inbound/outbound volume and counts |
| `mv_entity_daily` | wallet × day | an activity trend for one counterparty |
| `mv_global_daily` | day | the site-wide series behind [`/stats`](https://www.roundhouse.studio/stats) |

They refresh on a schedule, so they trail the tip of the chain by up to an hour. Read surfaces fold
in the newer settlements at read time, which is why a profile page and a raw `mv_entity_rollups`
query can differ by a few rows — the page is more current, not wrong.

## Rate limits and keys

| Caller | SQL queries / minute |
| --- | --- |
| Anonymous | 30 |
| Trial key from [`/v0/test/x402`](https://www.roundhouse.studio/docs/guides/first-x402-payment) | 240, for 30 days |
| Organisation key | Metered in Query Units instead |

Send a key as `authorization: Bearer rh_live_…` or `x-api-key`. Organisation keys are created in
[the dashboard](https://www.roundhouse.studio/dashboard/team); the trial key costs one cent and needs no account at all.

## Next steps

- [SQL over the index](https://www.roundhouse.studio/docs/data/sql) — the tables, and queries to copy
- [The data model](https://www.roundhouse.studio/docs/data/data-model) — what a settlement row actually contains
- [Coverage and confidence](https://www.roundhouse.studio/docs/data/coverage-and-confidence) — when to trust a number

---

Every page in these docs is available as markdown at its own URL plus `.md`.
Full index: https://www.roundhouse.studio/docs.md