For developers
AcreEyes API guide
Everything you need to run AcreEyes reports from your own code with AcreEyes Pro. For every endpoint's parameters and response schema, see the API reference.
The AcreEyes API runs the same parcel report you get on acreeyes.com, from your own code. You send a parcel number, address or point. AcreEyes checks it against the eight Eyes (Water, Land, Access, Build, Service, Hazard, Farm and Title), and you get back the full report as JSON and as the PDF.
- Base URL:
https://acreeyes.com/api/v1 - Format: JSON in and out, apart from the PDF, the map images and the live stream
- Machine-readable spec:
GET /openapi.json(https://acreeyes.com/api/v1/openapi.json) - Python client: acreeyes_client.py and the command-line script acreeyes.py
Contents
- Getting started
- How a report works
- Python client and command-line script
- Endpoint reference
- The run object
- Live events
- The report JSON
- Errors
- Plans, limits and retries
- What a report is and isn’t
Getting started
Your key
API access comes with AcreEyes Pro. Create a key yourself in the console: open acreeyes.com/app, go to Account → API keys, name the key (for example “CRM sync”) and choose Create key. Reports you start with it come out of your monthly Pro credits, the same as reports run in the console. You can hold up to five keys at once and revoke any of them there; a revoked key stops working at once.
A key looks like ae_live_1a2b3c4d_…. It is shown once, so store it somewhere safe, such as
a secrets manager or an environment variable. Don’t commit it to code. If you lose it, revoke
it and create another.
Send the key in the Authorization header on every request:
Authorization: Bearer ae_live_1a2b3c4d_…
The API refuses a key placed in a URL (400 key_in_url), because URLs end up in logs. If
that happens, revoke that key in the console and create a new one.
Your first report
export ACREEYES_API_KEY=ae_live_…
A="Authorization: Bearer $ACREEYES_API_KEY"
B=https://acreeyes.com/api/v1
curl -s -H "$A" $B/me # your key and this month's usage
# Start a report
curl -s -H "$A" -H 'Content-Type: application/json' -H 'Idempotency-Key: my-first-report' \
$B/runs -d '{"pin": "RP58N02E070150A", "state": "ID"}'
# → {"id": "run_82a633ab626a2341", "status": "queued", …}
# Wait for it: poll, or watch it live
curl -s -H "$A" $B/runs/run_82a633ab626a2341
curl -sN -H "$A" $B/runs/run_82a633ab626a2341/stream
# When status is "done", result.report links to the report
curl -s -H "$A" $B/analyses/<result.id>/report.json > report.json
curl -s -H "$A" $B/analyses/<result.id>/pdf -o report.pdf
A report usually takes one to three minutes. Each one checks more than a dozen state and federal systems, and the slowest of them sets the pace.
How a report works
| Term | What it is |
|---|---|
| Run | One request to analyze a parcel. It is queued, then running, then finished. You start it with POST /runs. |
| Analysis | What a successful run saves to your library: the parcel’s data and score. It has a stable id such as 20261003-103807-rp58n02e070150a. |
| Report | An analysis presented as the full report, either JSON (report.json) or PDF. You can fetch either as many times as you like at no extra cost. |
| Charge | One report counts against your monthly plan when a run finishes and saves an analysis. Failed and cancelled runs are free, and so are runs interrupted by a restart on our side. Deleting a report does not refund it. |
Your library is private to your account: you see your own runs and analyses only.
Python client and command-line script
acreeyes_client.py is a single file that uses only the
Python standard library (3.9+); copy it into your project.
acreeyes.py is a ready-made command-line tool built on it. Keep
the two files in the same folder.
from acreeyes_client import AcreEyes, RunFailed, PlanError
ae = AcreEyes() # reads ACREEYES_API_KEY (and ACREEYES_API_URL, if set)
def progress(ev):
if ev.name == "stage":
print(f"[{ev.data['t']:.0f}s] {ev.data['stage']}")
try:
report = ae.analyze(pin="RP58N02E070150A", state="ID", on_event=progress)
except RunFailed as e: # e.code: parcel_not_found, ambiguous_pin, run_failed
print(e.code, e.message, e.choices)
except PlanError as e: # e.code: quota, missing_scope, …
print(e.message)
else:
print(report["score"]["grade"], report["score"]["overall"])
for flag in report["flags"]:
print("⚠", flag)
ae.pdf(report["analysis"]["id"], "report.pdf")
| Method | Does |
|---|---|
analyze(pin=… | address=… | point=(lon, lat), state=, county=, profile=, weights=, on_event=, hide_owner=) |
Start a run, wait for it to finish, and return the report JSON |
start_run(...), wait(run_id, on_event=), run(id), runs(), cancel(id) |
Control the steps yourself |
stream(run_id) |
Iterate over live Event(name, data) objects |
logs(id), debug(id) |
See what a run did and where its time went |
report(id, hide_owner=), analysis(id), analyses(), pdf(id, path), share(id) |
Fetch your results |
resolve(parcel), me(), usage(month), regions(), profiles() |
Free checks and account info |
The client raises a typed error for each failure:
| Error | Status | Meaning |
|---|---|---|
AuthError |
401 | Missing, unknown, revoked or expired key |
PlanError |
403 | Your plan doesn’t allow it |
NotFound |
404 | No such run or analysis |
BadRequest |
400 | The request was invalid |
Busy |
429 | Rate limited, or a run is already pending |
Unavailable |
5xx | Server error, or the API couldn’t be reached |
RunFailed |
— | The run finished without a report |
Every error carries .code, .message and .request_id.
The client retries safely by itself on connection errors, server errors and 429 responses,
waiting as long as Retry-After asks. Each run start carries a generated
Idempotency-Key, so a retried start can never create or charge a second run.
Command line
python acreeyes.py --pin RP58N02E070150A # live progress, then a summary
python acreeyes.py --address "1234 Cross Mtn Rd, Sandpoint, ID" --pdf report.pdf
python acreeyes.py --point -116.55 48.27 --json report.json --hide-owner
python acreeyes.py --pin RP58N02E070150A --check # check the parcel resolves first (free)
python acreeyes.py --pin … --profile water --weight hazard=0.5
python acreeyes.py --pin … --json - --quiet | jq .score # report JSON on stdout
python acreeyes.py --run run_82a633ab626a2341 # an existing run
python acreeyes.py --me # your plan and usage
| Exit code | Meaning |
|---|---|
| 0 | Report ready |
| 1 | The run failed |
| 2 | Parcel not found, or the PIN is ambiguous (the script prints --county choices) |
| 3 | Key or plan refused |
| 4 | API unreachable, busy, or timed out |
Endpoint reference
Paths are relative to https://acreeyes.com/api/v1. All of them need the key except
/health and /openapi.json.
Account
| Method | Path | Returns |
|---|---|---|
| GET | /health |
{"ok": true, "api": "v1", "version"} |
| GET | /me |
Your key (name, scopes, expires_at), your plan (quota_month, used, pending, remaining, resets) and your limits (rate_per_min, max_pending) |
| GET | /usage?month=YYYY-MM |
Charged runs in that month (default: this month, UTC) |
| GET | /regions |
The states your account covers. A parcel in any other state is refused with not_covered. |
| GET | /profiles |
Weighting profiles and the eye names weights accepts |
Runs
| Method | Path | Body or query | Returns |
|---|---|---|---|
| POST | /resolve |
{"parcel", "state", "county"?} |
A free check that a PIN or address resolves. Always 200, with status: verified, unverified, not_found or unavailable. |
| POST | /runs |
See below. Optional Idempotency-Key header. |
202 with a new run, or 200 with the original run if the idempotency key was seen before |
| GET | /runs?status=&since=&before=&limit= |
{"runs": [...], "next"}. Pass next as before to get the next page. Newest first; limit can be up to 200. |
|
| GET | /runs/{id} |
The run | |
| POST | /runs/{id}/cancel |
The run, which ends cancelled and is never charged |
|
| GET | /runs/{id}/logs?after=N |
{"lines", "next", "finished"}: the run’s progress, line by line (stages, flags and the result line) |
|
| GET | /runs/{id}/stream |
Live events (see below) | |
| GET | /runs/{id}/debug |
Where the time went: stages, sections, lookups (requests, errors, seconds and cache hits in total) and failed_lookups (how many checks did not answer) |
POST /runs body. Give exactly one of pin, address or point.
{
"pin": "RP58N02E070150A",
"address": "1234 Cross Mtn Rd, Sandpoint, ID",
"point": [-116.55, 48.27],
"state": "ID",
"county": "Bonner",
"profile": "water",
"weights": {"hazard": 0.5},
"eyes": ["water"],
"well_radius_miles": 2,
"good_well_gpm": 10,
"stream_radius_miles": 1,
"advertised_acres": 20
}
pointis longitude then latitude.advertised_acres(optional) is the acreage the listing advertises, a number from 0.01 to 1,000,000. The report compares it with the mapped parcel’s acreage and never uses it in its place. When the two are far apart the report says so on page 1, and when the listing is smaller it warns that only part of the parcel may be for sale and that the findings describe the whole mapped parcel. A large gap holds the grade until the land for sale is confirmed. Any other value fails the run with a 400 and starts nothing.pincan list the parcels of one holding separated by commas: at most 10, connected to each other (sharing a boundary, or across a mapped road right-of-way), with the same owner of record. Otherwise the run fails with aholding_*code (below). A PIN whose township or range letter was typed as a digit (RP36N043250002forRP36N04E250002) is corrected only when exactly one parcel fits and it joins the others with the same owner; the report lists every correction.countyis only needed when a PIN exists in more than one county. The run then endsambiguous_pinand lists the choices.profileandweightsset how the eyes are weighted in the score. The data checked is the same either way.eyes(optional; default all eight) picks the eyes the report shows:water,land,road,build,utility,hazard,farm,title. Every lookup still runs, so it costs the same. A partial report says so on page 1, its score covers only the eyes it shows (no score if those are onlyutility/farm), and the report JSON carries ascopeobject (nullfor a full report). Share links keep the eyes they were created with.
Analyses and reports
| Method | Path | Returns |
|---|---|---|
| GET | /analyses |
Your library: one summary row per analysis, newest first |
| GET | /analyses/{id} |
The raw analysis: summary, the full engine result, the parcel geometry (GeoJSON) and links |
| GET | /analyses/{id}/report.json?hide_owner=&compact= |
The full report as JSON (see below) |
| GET | /analyses/{id}/pdf?hide_owner=&brand= |
The PDF report. brand adds a “Prepared by” line. |
| GET | /analyses/{id}/maps/{name}.png |
One report map. Names are listed in each eye’s maps. A map drawn over the aerial photo is a JPEG (Content-Type: image/jpeg); read the header, not the extension. |
| POST | /analyses/{id}/share |
{"prepared_for"?, "brand"?, "hide_owner"?, "listing_url"?} returns {"code", "url"}, a public link to the report as a web page. The owner is hidden unless you set "hide_owner": false. listing_url (an http(s) link to your listing) adds a “View the listing” button to the page and a link plus a QR code to its PDF. |
You can add ?profile= and ?weights= to the analysis, report and PDF reads to view them
under another weighting. Nothing is re-run and nothing is charged.
The run object
{
"id": "run_82a633ab626a2341",
"kind": "analyze",
"status": "done",
"created_at": "2026-10-03T17:35:45.227Z",
"started_at": "2026-10-03T17:35:45.674Z",
"ended_at": "2026-10-03T17:38:14.561Z",
"exit_code": 0,
"request": {"pin": "RP58N02E070150A", "state": "ID"},
"idempotency_key": "my-first-report",
"result": {"kind": "analysis", "id": "20261003-103807-rp58n02e070150a",
"url": "/v1/analyses/20261003-103807-rp58n02e070150a",
"report": "/v1/analyses/20261003-103807-rp58n02e070150a/report.json"},
"charged": true,
"error": null,
"upstream": {"duration_s": 148.5, "http_requests": 123, "http_errors": 25, "cache_hits": 1,
"failed_lookups": 1},
"links": {"self": "…", "logs": "…", "stream": "…", "debug": "…"}
}
status is one of:
| Status | Meaning |
|---|---|
queued |
Waiting for a slot |
running |
In progress |
done |
Finished; result is set |
failed |
Finished without a report; see error |
cancelled |
You cancelled it |
interrupted |
Our server restarted during the run; start it again |
rejected |
We were too busy to accept it; try again shortly |
None of failed, cancelled, interrupted or rejected is charged.
error.code is one of:
| Code | Meaning |
|---|---|
parcel_not_found |
The parcel didn’t resolve. Check the number or address. |
not_covered |
The parcel is in a state your account doesn’t cover. GET /regions lists the ones it does. |
ambiguous_pin |
The PIN exists in several counties. Start again with county. While the run is fresh, choices lists the candidates. |
holding_disconnected |
Several PINs were sent, but the parcels don’t adjoin each other (directly, or across a mapped road right-of-way). One report covers one holding. |
holding_connectivity_unverified |
The parcels might connect across a gap, but the public records needed to check it didn’t answer. Try again later. |
holding_owner_mismatch |
The parcels have different owners of record. One report covers one owner’s holding. |
holding_owner_unverified |
One owner of record couldn’t be confirmed for every parcel. Screen the parcels separately. |
holding_limit |
More parcels or acres than one report covers (10 parcels / 2,560 acres). Screen the property in parts. |
holding_overlap |
Two of the PINs describe the same land. |
run_failed |
Something else went wrong. error.message has the last lines of output, and /debug has the detail. |
upstream shows how much the public data services were used. It can show
http_errors above zero even on a good run, because slow services are retried.
failed_lookups counts checks that did not answer. The report marks each of those as
not checked, never as a pass.
Live events
GET /runs/{id}/stream is a server-sent events
stream. Every progress line arrives as a plain message whose data is a JSON string. Typed
events arrive alongside those lines:
| Event | Data |
|---|---|
| (none) | "· checking wells…": one output line |
stage |
{"stage", "index", "t", "prev", "prev_seconds"}: a step started. t is seconds since the run began; prev_seconds is how long the previous step took. |
flag |
{"text"}: a finding worth investigating |
result |
{"kind", "id", "url", "report"}: the analysis was saved |
choices |
{"pin", "candidates": [{county, pin, acres, address}]}: the PIN is ambiguous |
end |
The final run object. The stream closes after this event. |
A comment line (: ping) arrives every 15 seconds while nothing else happens. If the
connection drops, the run carries on: reconnect, or poll GET /runs/{id}.
The due-diligence sections run in parallel and each reports when it finishes, so their
prev_seconds is the gap between finishes, not how long a section took. /debug has the
real time for each section.
// Browser or Node 18+: fetch-based reader (EventSource can't send headers)
const res = await fetch(`${B}/runs/${id}/stream`, {headers: {Authorization: `Bearer ${KEY}`}});
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buf = "";
for (;;) {
const {value, done} = await reader.read();
if (done) break;
buf += value;
let i;
while ((i = buf.indexOf("\n\n")) >= 0) {
const block = buf.slice(0, i); buf = buf.slice(i + 2);
const ev = /^event: (.*)$/m.exec(block)?.[1] ?? null;
const data = block.split("\n").filter(l => l.startsWith("data: ")).map(l => l.slice(6)).join("\n");
if (data) console.log(ev, JSON.parse(data));
}
}
The report JSON
GET /analyses/{id}/report.json returns everything the PDF says, as data, in the same
words and the same order. It is built from the same report model as the PDF, so the two
can’t disagree. The schema is named in the document ("schema": "acreeyes.report/2").
Fields may be added within a version. A field will not be removed or change meaning
without a new schema name.
What the API leaves out. Reports give you the findings, the evidence behind each one
(recorded, estimated, likely, not checked) and what to verify next. They do not name the
data providers, datasets or services AcreEyes reads, and they do not link to outside record
systems. Version 2 (2026-11) is version 1 without those fields: parcel.site_address_source,
parcel.owner_source, the link column of tables.well_logs and tables.water_rights,
and any field naming a source or dataset. In tables.water_rights, source is still the
water a right draws from (for example GROUND WATER or a creek’s name). The same applies
to /analyses/{id}, the run upstream digest (no slowest_hosts), /runs/{id}/debug
(totals in lookups, no host list) and the run logs and stream (progress in plain words).
Add compact=true to leave out the per-Eye detail (eyes, tables, holding_explorer).
The result is about a quarter of the size, and its omitted field lists what was left out.
| Field | Contents |
|---|---|
schema, generated_at, generator |
Document identity |
analysis |
id, created, query |
parcel |
pin, county, state, acres_gis, site_address, plus owner (left out with hide_owner) |
score |
overall (0–100), grade (A–F), status (graded or incomplete), held (why the grade is held, if it is), access_adjustment (what the capped Access Eye took off the overall, 0 or less), coverage, confidence, adjusted, profile, note |
farm |
The Farm Eye’s own grade, status and score |
flags |
Findings worth investigating before an offer (strings) |
brief |
The decision brief, as on the PDF cover: read (score, grade, coverage); strengths[] (eye, headline); concerns[] (eye, topic, severity high/medium/low, evidence strong/moderate/limited, headline, detail, next); next_steps[] (what to do next); coverage[] (area, status: Checked, Estimated, Partial, No public mapping or Not checked; note) |
key_facts |
Headline numbers, such as relief_ft, wells_logged, gpm_median, well_depth_median_ft, expected_gpm, flood_status, sfha_acres, wetland_acres, septic_rating, frontage_ft, road_class, access_kind, assessed_value, streams_crossing and river_frontage_ft (feet of the parcel line on a river’s bank). le10_slope_pct is the share of the parcel at ≤10% slope; wells_logged and gpm_median count only wells that logged a yield (a logged 0 is an unrecorded field). A value is null when it wasn’t checked. |
eyes[] |
One entry per eye, in report order (see below) |
tables.well_logs |
{rows: [{where, use, gpm, swl_ft, depth_ft, casing, year}], total}: the closest driller logs |
tables.water_rights |
{rows: [{number, on_parcel, priority, uses, source, cfs, status}], total} (source: the water the right draws from) |
notes |
Notes the analysis recorded |
disclaimer |
The report’s full disclaimer |
About the score fields:
coverageis how much of the weighted evidence answered. Anincompletestatus means too little answered to give a letter grade.confidenceis kept for compatibility. It measures how much of the weighted evidence answered; it is not a confidence in the outcome.- The score ranks parcels for follow-up. It is not validated against real-world outcomes and is not a forecast of cost, value or what can be built.
Each eye
The eyes are, in report order: Water, Land, Access, Build, Service, Hazard, Farm and Title. Each entry has:
| Field | Contents |
|---|---|
key, name, title_suffix, looks_at |
Which eye this is and what it examines |
score, grade, grade_status, coverage, weight, unscored |
The eye’s own result. unscored eyes (such as Farm) are reported but don’t feed the overall score. |
word, phrase, gate |
What the report prints beside the number: the word (“Favorable”, or for Access an evidence word such as “Verification needed” or “Maintenance unknown — records unavailable”), the full phrase with its qualifiers, and the open question when the letter is withheld (grade_status review) |
Access only: qualifiers[], uncapped_score, adjustment, ceilings[], access_summary, access_states |
Why the Access score is limited. uncapped_score is the Eye before its evidence ceilings; ceilings[] lists each one (key, score, word, short, why, blocks_overall_a, binding). access_summary is {headline, rows[]}: rows for legal access, maintenance, winter plowing and route elevation and grade, each {label, state, text, needed}. access_states gives each one’s state, such as legal: inferred_plat or maintenance: unknown_omitted. AcreEyes does not search title documents, so legal access is never more than inferred unless verified evidence was supplied. |
headlines |
The eye’s main findings, one line each |
components[] |
{key, label, score, weight, estimated, reasons[]}: what the score is made of, and why |
facts[] |
{block, label, text, links?}: the report’s fact rows for this eye |
tables[] |
{block, title, columns, rows}: the eye’s tables, such as slope bands, soil map units, crop fit, livestock and streams |
notes[] |
{block, text}: explanatory notes printed with the tables |
not_checked[] |
{label, text}: checks that didn’t answer. Unknown is never a pass. |
cannot_see |
What this eye cannot see from public data |
maps |
Map names for /analyses/{id}/maps/{name}.png |
jq '{grade: .score.grade, score: .score.overall, flags}' report.json
jq '.eyes[] | {eye: .name, grade, not_checked: [.not_checked[].label]}' report.json
jq -r '.eyes[] | select(.key=="water") | .facts[] | "\(.label): \(.text)"' report.json
jq '.tables.well_logs.rows[] | {where, gpm, depth_ft, year}' report.json
Errors
Every error has the same shape, and the request_id is also sent in the X-Request-Id
header:
{"error": "quota", "message": "This key has used 25 of its 25 reports this month. The count resets on 2026-11-01.", "request_id": "req_8b004ce728d352bf"}
| Status | error |
What to do |
|---|---|---|
| 400 | bad_request |
Fix the field named in message |
| 400 | key_in_url |
Send the key in the header, then revoke that key in the console and create a new one |
| 401 | unauthorized |
Check the key; it may be revoked or expired |
| 403 | quota |
This month’s reports are used. The message says when the count resets. |
| 403 | missing_scope |
Your key can’t do this |
| 403 | not_subscribed |
The plan behind this key isn’t active |
| 403 | api_closed |
API access isn’t open for your account yet |
| 404 | not_found |
No such run or analysis in your account |
| 429 | rate_limited |
Wait for Retry-After seconds |
| 429 | busy |
A run is already pending for your key, or we’re at capacity. Wait for Retry-After. |
| 503 | membership_unavailable |
We couldn’t check your plan just then; retry shortly |
| 500 | internal |
Retry. If it persists, send us the request_id. |
When you contact us about a request, include its request_id (or the run id). We can
see exactly what happened from either.
Plans, limits and retries
| Limit | Default |
|---|---|
| Reports per month | Set by your plan; see GET /me. Counted per UTC calendar month. |
| Runs at once | 1 per key. Start the next one when the current one finishes. |
| Requests | 60 per minute per key. Each response carries RateLimit-Limit and RateLimit-Remaining. |
| Idempotency keys | 1–128 printable ASCII characters, unique for each run you intend |
Idempotency. Send an Idempotency-Key header with every POST /runs, for example
your own record id. If a network error leaves you unsure whether a run started, send the
same request with the same key: you get the original run back, and nothing is charged
twice. A start we turn away as busy releases its key, so retrying it starts a fresh run.
Batches. Start runs one at a time per key, and wait for each to finish before starting the next.
What a report is and isn’t
AcreEyes analyzes public records and GIS data to show where a parcel needs a closer look.
It is a screening report. It is not a survey, appraisal, title opinion, septic or perc
approval, flood determination, water-right opinion, insurance determination,
environmental site assessment or determination of what can be built. Verify anything you
rely on with the county and licensed professionals. Every report includes its full
disclaimer (disclaimer in the JSON).
