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

  1. Getting started
  2. How a report works
  3. Python client and command-line script
  4. Endpoint reference
  5. The run object
  6. Live events
  7. The report JSON
  8. Errors
  9. Plans, limits and retries
  10. 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
}
  • point is 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.
  • pin can 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 a holding_* code (below). A PIN whose township or range letter was typed as a digit (RP36N043250002 for RP36N04E250002) is corrected only when exactly one parcel fits and it joins the others with the same owner; the report lists every correction.
  • county is only needed when a PIN exists in more than one county. The run then ends ambiguous_pin and lists the choices.
  • profile and weights set 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 only utility/farm), and the report JSON carries a scope object (null for 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:

  • coverage is how much of the weighted evidence answered. An incomplete status means too little answered to give a letter grade.
  • confidence is 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).