Listing fields

GET /v1/fields returns your registered fields one page at a time, oldest first. Use it to reconcile AgroSat with your own database.

Python and JavaScript examples reuse API, session and headers from the Quickstart.

Pages and cursors

Parameter	Notes
limit	Page size, 1 to 200. Default 50.
cursor	next_cursor from the previous page. Leave it out for the first page.
external_id	Return only the field with this identifier.

Each page carries next_cursor next to data. A page requested with limit=1:

{
  "success": true,
  "data": [
    {
      "id": "cmgz7k2qv0004l8p3a9d1x6rt",
      "external_id": "f-1001",
      "name": "North parcel 3",
      "area_ha": 41.53,
      "status": "ready",
      "created_at": "2026-04-28T09:14:03.512Z"
    }
  ],
  "next_cursor": "MjAyNi0wNC0yOFQwOToxNDowMy41MTJafGNtZ3o3azJxdjAwMDRsOHAzYTlkMXg2cnQ"
}

Pass next_cursor back as cursor to get the next page. On the last page next_cursor is null. Treat the cursor as an opaque string: don’t build or edit it.

Read every page

A single response is not the full list once you have more fields than limit. Keep requesting until next_cursor is null.

curl

cursor=""
while :; do
  page=$(curl -s -G https://api.agrosat.uz/v1/fields \
    -H "X-API-Key: $AGROSAT_API_KEY" \
    --data-urlencode "limit=200" \
    ${cursor:+--data-urlencode "cursor=$cursor"})
  echo "$page" | jq -r '.data[] | [.external_id, .id, .status] | @tsv'
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Python

def all_fields(session):
    params = {"limit": 200}
    while True:
        r = session.get(f"{API}/fields", params=params, timeout=30)
        r.raise_for_status()
        page = r.json()
        yield from page["data"]
        if page["next_cursor"] is None:
            return
        params["cursor"] = page["next_cursor"]

by_external_id = {f["external_id"]: f for f in all_fields(session)}

JavaScript

async function* allFields() {
  let cursor = null;
  do {
    const url = new URL(`${API}/fields`);
    url.searchParams.set("limit", "200");
    if (cursor) url.searchParams.set("cursor", cursor);
    const page = await (await fetch(url, { headers })).json();
    if (!page.success) throw new Error(`${page.error.code}: ${page.error.message}`);
    yield* page.data;
    cursor = page.next_cursor;
  } while (cursor !== null);
}

for await (const field of allFields()) console.log(field.external_id, field.status);

A field registered while you walk the list appears on a later page. A deleted field disappears from every page.

Find a field by your identifier

curl -G https://api.agrosat.uz/v1/fields \
  -H "X-API-Key: $AGROSAT_API_KEY" \
  --data-urlencode "external_id=f-1001"

data holds the matching field, or is empty if there is none. Listing costs no units.

Next steps

Registering fieldsIdempotent registration and deletion.

ErrorsWhat invalid_request on a bad cursor means.