Reports API: Generate and Download Agronomic Analyses

Generate scouting summaries, seasonal analyses, and variable-rate prescription maps for your fields and download them as PDF, JSON, or CSV files.

The Reports API lets you generate structured agronomic analyses for your fields and download the results in PDF, JSON, or CSV format. Reports are generated asynchronously — you submit a request, poll for status (or use a webhook), and download the file once it is ready. Report types range from field scouting summaries and seasonal health overviews to variable-rate prescription maps for precision application equipment.

The Report Object

id · string

The unique identifier for the report. Prefixed with rpt_.

field_id · string

The ID of the field this report was generated for.

type · string

The report type. One of scouting, seasonal, health_summary, or prescription.

format · string

The output format. One of pdf, json, or csv.

status · string

The current processing status. One of:

• pending — The report has been queued and has not started processing.
• processing — The report is actively being generated.
• ready — The report is complete and available for download.
• failed — Report generation failed. Retry the request or contact support if the issue persists.

created_at · string

ISO 8601 timestamp of when the report was requested.

download_url · string

A pre-signed URL to download the completed report. Populated only when status is ready. This URL expires after 7 days — see the note below.

expires_at · string

The ISO 8601 timestamp at which the download_url expires. After this time, re-fetch the report object to obtain a refreshed URL, or regenerate the report.

---

Generate a Report

Request a new report for a field. Report generation runs asynchronously. The API returns 202 Accepted immediately with a report object in pending status. Poll GET /reports/{id} or subscribe to the report.ready webhook event to know when the report is available for download.

Path Parameters

id · string · required

The unique field ID.

Request Body

type · string · required

The type of report to generate. Accepted values:

• scouting — A point-in-time field health snapshot with anomaly highlights and scouting zone recommendations.
• seasonal — A full-season analysis covering crop development, NDVI progression, and yield potential estimates.
• health_summary — A concise weekly or monthly health summary with index trends and alert history.
• prescription — A variable-rate application map for inputs such as fertiliser or seed, derived from index variability zones.

format · string · required

The output file format. Accepted values: pdf, json, csv.

• pdf — A formatted report suitable for sharing with agronomists or farmers.
• json — Machine-readable structured data for integration with other systems.
• csv — Tabular data export suitable for spreadsheet analysis.

options · object

Additional configuration for the report type. Available options vary by type.

Show options properties

start_date · string

The start of the analysis period (ISO 8601 date). Applicable to seasonal and health_summary types.

end_date · string

The end of the analysis period (ISO 8601 date). Applicable to seasonal and health_summary types.

index · string

The vegetation index to use as the basis for the report (e.g., NDVI, NDRE). Defaults to NDVI.

prescription_input · string

For prescription reports only — the input to vary (e.g., nitrogen, seed_rate).

Example Request

curl -X POST https://api.example.com/v1/fields/fld_01j8xyz/reports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "seasonal",
    "format": "pdf",
    "options": {
      "start_date": "2024-05-01",
      "end_date": "2024-09-30",
      "index": "NDVI"
    }
  }'

---

Get a Report

Retrieve the current status and details of a report. Poll this endpoint after submitting a report request, or use the report.ready webhook event to avoid polling altogether.

Path Parameters

id · string · required

The unique report ID (e.g., rpt_01j9def).

Example Request

curl https://api.example.com/v1/reports/rpt_01j9def \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "rpt_01j9def",
  "field_id": "fld_01j8xyz",
  "type": "seasonal",
  "format": "pdf",
  "status": "ready",
  "created_at": "2024-10-01T10:00:00Z",
  "download_url": "https://reports.example.com/rpt_01j9def.pdf",
  "expires_at": "2024-10-08T10:00:00Z"
}

The download_url expires 7 days after the report is generated. If the URL has expired, call GET /reports/{id} again — the response will contain a freshly signed URL valid for another 7 days.

---

List Reports

Retrieve a paginated list of all reports in your account, optionally filtered by field, type, or status.

Query Parameters

field_id · string

Filter reports to a specific field.

type · string

Filter by report type. Accepted values: scouting, seasonal, health_summary, prescription.

status · string

Filter by processing status. Accepted values: pending, processing, ready, failed.

page · integer · default: "1"

The page number to retrieve.

per_page · integer · default: "20"

The number of reports per page. Maximum 100.

Example Request

curl "https://api.example.com/v1/reports?field_id=fld_01j8xyz&status=ready" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Delete a Report

Permanently delete a report and its associated download file. Returns 204 No Content on success.

Path Parameters

id · string · required

The unique report ID.

Example Request

curl -X DELETE https://api.example.com/v1/reports/rpt_01j9def \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting a report is irreversible. If you need the same analysis again, submit a new POST /fields/{id}/reports request to regenerate it.