# Life of a lookup

URL: /products/data/life-of-a-lookup · Id: `page:products/data/life-of-a-lookup`

> One sales-tax lookup from a checkout: the free coverage check, the keyed call, the answer with its Sources and times, and the one billed hit.

A lookup asks a [Dataset](/business/nouns/dataset) what is true of one key. This chapter follows one call from Fernway Goods' checkout to Ratebook, on the customer's plane: `api.ratebook.dev`, with a key from Ratebook's [Portal](/business/nouns/portal).

## Covered first
Before it charges a card, the checkout asks whether the address is in coverage. The coverage check is a `HEAD` request on the same lookup, and it charges nothing.

```bash
curl -I "https://api.ratebook.dev/rates/lookup?address=500%20Pine%20St%2C%20Seattle%2C%20WA" \
  -H "Authorization: Bearer $RATEBOOK_KEY"
```

The answer says the address is covered and what the lookup costs. An address outside coverage gets the same answer before any money moves. [Coverage](/products/data/coverage) covers the map behind it.

## The call
The checkout sends the lookup with its live key, which begins `ratebook_sk_live_`.

```bash
curl "https://api.ratebook.dev/rates/lookup?address=500%20Pine%20St%2C%20Seattle%2C%20WA" \
  -H "Authorization: Bearer $RATEBOOK_KEY"
```

The answer is every jurisdiction that taxes the address: the state, the county, the city and a transit district. Each carries its rate, its share of the total, its effective date and the authority that set it.

## Every value with its origin
Each value names its [Source](/business/nouns/source) and three times: when the rate took effect, when the authority published it, and when Ratebook last read it. A checkout that files returns keeps those with the order, and its auditor reads the same answer a year later.

| Field | Answers |
| --- | --- |
| `observedAt` | When the rate was true |
| `publishedAt` | When the Source published it |
| `refreshedAt` | When the Dataset last read that Source |

[Provenance](/products/data/provenance) has every field.

## Counted once
The [Meter](/business/nouns/meter) counts the lookup as one billed hit. The same address again inside 24 hours counts once, so a checkout that retries or re-renders pays for one answer.

A miss returns an empty result, not an error, and counts as a free miss. The Portal's usage view splits billed hits from free misses, so Fernway Goods sees what it paid for.

## On the builder's side
Ratebook's founder reads the same call from the builder's plane, at `api.sb/ratebook.dev` with the `startup-builder` package: the [Action](/business/nouns/action), its cost and the Meter [Entry](/business/nouns/entry). The customer's plane never shows [api.sb](/code/platform/api-sb), and the builder's never needs the customer's key.

## A year later
The rate changes on `2027-01-01`, and Ratebook's daily refresh records the new value beside the old one. A lookup with `at` set to the order's date returns the rate as it stood then. [As-of reads](/products/data/as-of-reads) covers reading the past.

## Next
The [lifecycle](/products/data/lifecycle) page follows the Dataset itself, from its file to its retirement.