---
title: "Get started with LookValid (agent playbook)"
url: "https://lookvalid.com/get-started.md"
canonical_url: "https://lookvalid.com/get-started.md"
last_updated: "2026-10-22"
type: "guide"
summary: "The steps an AI agent follows to get a LookValid API key and make a first call."
related: ["https://lookvalid.com/docs/quickstart.md", "https://lookvalid.com/docs/mcp.md"]
---

# Get started with LookValid (agent playbook)

The steps an AI agent follows to get a LookValid API key and make a first call.

You are an AI agent. Do the steps below yourself where you can. Pause only for the three things a person must do: ask for an account, add billing, and approve spending credits.

## 1. Get an API key (a person does this)

1. Ask the person to email hello@lookvalid.com with the lookups they need. We set up the account and send the key.
2. Do not create accounts, enter payment details or buy credits on the person's behalf.
3. Keys start with `lv_live_`. A key is shown once, when it is created.
4. Put the key in the environment variable `LOOKVALID_API_KEY`. Never print it, log it or put it in a URL.

## 2. Read the contract

- No API host is published on this site, so do not guess one. The host comes with the key.
- Read the [API reference](https://lookvalid.com/docs/api.md) before choosing an operation; do not guess endpoints or fields.
- Authentication: `Authorization: Bearer $LOOKVALID_API_KEY` (or an `X-API-Key` header).
- Every lookup lists its credit cost on its reference page. Account endpoints are free.
- Errors use one envelope: `{"error": {"code", "message", "fix", "docs_url", "retryable", "request_id"}}`. Branch on `code`. The [error reference](https://lookvalid.com/docs/errors.md) lists every code.

## 3. Try a lookup without a key

The [free tools](https://lookvalid.com/tools.md) need no key and no credits. Each page runs the lookup for the person using it, with a limit per address.

## 4. Spend credits carefully

- Ask the person for approval before running many lookups or anything that could spend a large number of credits.
- Repeating the same lookup within the cache window is free, so reuse earlier results instead of asking again.
- On HTTP 429 wait the number of seconds in `Retry-After`. On `insufficient_credits` stop and tell the person; do not retry.

## Where to look next

- [Quickstart](https://lookvalid.com/docs/quickstart.md), [authentication](https://lookvalid.com/docs/authentication.md), [credits and billing](https://lookvalid.com/docs/credits-and-billing.md), [rate limits](https://lookvalid.com/docs/rate-limits.md)
- [API reference](https://lookvalid.com/docs/api.md)
- [Pricing](https://lookvalid.com/pricing.md)
- [Free tools](https://lookvalid.com/tools.md)
- Every page as markdown: [sitemap](https://lookvalid.com/sitemap.md) and [documentation sitemap](https://lookvalid.com/docs/sitemap.md), or [llms.txt](https://lookvalid.com/llms.txt) for the short index
- Machine-readable discovery: [/.well-known/ai-catalog.json](https://lookvalid.com/.well-known/ai-catalog.json)
- Every error code has its own page: start from the [error reference](https://lookvalid.com/docs/errors.md)
- Support: hello@lookvalid.com

## Related

- [Quickstart](https://lookvalid.com/docs/quickstart.md)
- [MCP server](https://lookvalid.com/docs/mcp.md)