A JSON HTTP API for programmatic skip tracing. New to it? Start with the quickstart.
All requests go to:
Every request carries your key as a bearer token. Generate a key in the API section of your dashboard (included on Pro). Keys are shown once — store them as a secret and never ship them to the browser.
API searches spend the same credits as the dashboard — there is no per-call fee. Cost is the sum of the fields you request, and a call is charged only when a person is found. A miss costs nothing.
Run a trace. Send a JSON body:
| Field | Type | Description | |
|---|---|---|---|
query | string | required | What to search: an address, name, phone, or email. Aegis detects the mode. Max 200 characters. |
fields | string[] | optional | Which fields to return: name, age, email, phone, address, associate. Omit to return everything. |
maxResults | number | optional | How many people to return, 1–10. Each additional result multiplies credit cost. Defaults to the measured optimum. |
curl -X POST https://metorys.com/api/v1/search \
-H "Authorization: Bearer aegis_sk_..." \
-H "Content-Type: application/json" \
-d '{
"query": "1233 Silver Arrow Ct, Fort Mill SC",
"fields": ["name", "phone", "email"],
"maxResults": 2
}'results is an array of records (one per person, up to maxResults). Each record is found or not_found. Unrequested fields are omitted.
{
"query": { "input": "1233 Silver Arrow Ct, Fort Mill SC", "mode": "address" },
"results": [
{
"status": "found",
"rank": 1,
"person": {
"firstName": "Robert",
"lastName": "Ledbetter",
"age": 58,
"current": {
"street": "1233 Silver Arrow Ct", "city": "Fort Mill",
"state": "SC", "postalCode": "29715",
"period": { "label": "Nov 2004 - May 2025" }
},
"phones": [
{ "display": "(828) 555-0104", "type": "Wireless",
"confidence": 94, "lastReported": "Jul 2026" }
],
"emails": [{ "address": "r.ledbetter@gmail.com" }],
"addresses": [ /* full residency history */ ],
"connections": [ /* relatives and associates */ ]
}
}
],
"creditsUsed": 4,
"creditsRemaining": 46
}Each field costs credits; the call charges their sum.
| Field | Credits | Returns |
|---|---|---|
name | 1 | First and last name. |
age | 1 | Age and month-precision birth date where available. |
email | 1 | Known email addresses, source-ranked. |
associate | 1 | Relatives and associates (name + age). |
phone | 2 | Phone numbers with line type, confidence score, and last-reported date. |
address | 2 | Current address plus full residency history with date ranges. |
| Status | Meaning | When |
|---|---|---|
| 200 | OK | A result (which may contain a not_found record). Credits charged only when a person is found. |
| 400 | Bad Request | Missing or invalid query. |
| 401 | Unauthorized | Missing, malformed, invalid, or revoked API key. |
| 402 | Payment Required | Not enough credits for this call. |
| 502 | Bad Gateway | The upstream lookup failed; retry. |
Generate a key and go.