Reports

The Reports API generates reports as CSV. Getting a report takes two requests: create it, then download it once it has generated.

The examples use an access token and the production base URL. With an API key, send x-api-key: {API key} in place of the Authorization header; see Authentication. For other environments, see Environments.

Create a reportCopy Anchor Link

Call Create Report with the report type, the farm to report on, and the reporting period:

curl https://api.agriwebb.com/v2/report \
  --header 'Authorization: Bearer {access token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "{report type}",
    "tenantType": "{tenant type}",
    "tenantId": "{farm ID}",
    "reportingPeriodStart": {start timestamp},
    "reportingPeriodEnd": {end timestamp}
  }'

• type is one of the reports listed under Reports in the sidebar, and tenantType is the tenant type listed on its page.
• reportingPeriodStart and reportingPeriodEnd are Unix timestamps in milliseconds.
• The credential needs the scopes listed for the report type. Marketplace partners request them in the Authorisation Request.

The response contains the report's ID as data.id, and its download URL as links.download:

{
  "data": {
    "id": "{report ID}",
    "type": "{report type}",
    "tenantType": "{tenant type}",
    "tenantId": "{farm ID}",
    "reportingPeriodStart": {start timestamp},
    "reportingPeriodEnd": {end timestamp},
    "status": "{status}",
    "creationDate": {timestamp},
    "lastModifiedDate": {timestamp}
  },
  "links": {
    "download": "https://api.agriwebb.com/v2/report/{report ID}"
  }
}

status is pending, created or failed. It is only updated when the report is downloaded, so call Get Report to find out whether a report is ready.

If a report with the same type, tenant and period was created in the last hour, the request returns that report, unless a download has already returned 424 for it. Send Cache-Control: max-age={seconds} to change the window, or Cache-Control: no-cache to always generate a new report.

Download a reportCopy Anchor Link

Call Get Report with the report ID and an Accept header of text/csv, or application/vnd.agriwebb.csv+v1 to pin version 1 of the CSV format:

curl --location https://api.agriwebb.com/v2/report/{report ID} \
  --header 'Authorization: Bearer {access token}' \
  --header 'Accept: text/csv'

PollingCopy Anchor Link

Poll Get Report until it stops returning 428. Wait a few seconds after creating the report, then back off between attempts, for example by doubling the wait from 5 seconds up to a minute.

Each attempt to generate a report is given up to 15 minutes. If Get Report still returns 428 after that, create the report again with Cache-Control: no-cache, so the request does not return the same report from the cache.

If the 302 redirect has expired, call Get Report again for a new one.

List reportsCopy Anchor Link

List Reports returns reports newest first: every report on the farms the credential can access, of the types its scopes allow.

curl https://api.agriwebb.com/v2/report \
  --header 'Authorization: Bearer {access token}'

Each entry has the same fields as data in the create response. Results are paginated, 100 per page by default and up to 1000 with perPage. Follow links.next until it is null.

links.download is a URL template for Get Report, where {id} is a report's id.