Analysis

Request grain sample analysis on an inventory and read the graded results. Samples are graded by SGS; MGX orchestrates the workflow, records the results, and handles billing. As the sample moves from request to graded, MGX emits webhooks so your platform can track it without polling.

The analysis.read and analysis.write scopes are granted to approved partners, not self-service. Contact us to enable them on your API client.

Who requests, who pays

Analysis works in two billing modes — both use the same endpoint, and which one applies is decided by who owns the inventory:

Self-billed. The token acts as a seller (via Login with MGX) requesting analysis on their own inventory. The seller's payment method on file with MGX is charged, with any subscription discounts applied.
Partner-billed. Your team requests analysis on inventory owned by a seller your team manages. Your team's payment method is charged the wholesale price, and you bill your own farmer off-platform. Subscription perks do not apply.

In both cases a physical sample must reach MGX, so the seller always exists in MGX — either as your own account or as a managed seller account your team created on their behalf.

A payment method must be on file before requesting analysis — the seller's (self-billed) or your team's (partner-billed). A request without one returns a 403 payment_method_required error.

GET/v1/analysis-types

List analysis offerings

The grading offerings you can request, with pricing. Partner clients see the wholesale price.

Response attributes

Name
id
Type
integer
Description
Pass these ids in the analysis_types field when requesting.
Name
name
Type
string
Description
The offering name.
Name
price
Type
number
Description
Price in the currency below.
Name
currency
Type
string
Description
ISO currency code, e.g. CAD.

Request

GET

/v1/analysis-types

curl https://api.mygrainexchange.com/v1/analysis-types \
  -H "Authorization: Bearer {token}"

POST/v1/me/inventory/:id/analysis

Request analysis

Request grading on an inventory you own (self-billed) or one a seller your team manages owns (partner-billed). Charges the appropriate payment method and queues the sample for SGS. Emits analysis.requested immediately, then analysis.sample_received, analysis.graded, and analysis.photo_added as the sample progresses.

Required attributes

Name
analysis_types
Type
array
Description
One or more analysis offering ids from the analysis-types endpoint.

Returns 409 if analysis was already requested for this inventory, and 404 if the inventory is neither yours nor managed by your team.

Request

POST

/v1/me/inventory/:id/analysis

curl https://api.mygrainexchange.com/v1/me/inventory/inv_3Kd9/analysis \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "analysis_types": [1] }'

GET/v1/me/inventory/:id/analysis

Get analysis status & result

The current status and, once grading is finalized, the full result and approved (buyer-visible) sample photos.

Response attributes

Name
status
Type
string
Description
Either pending or graded.
Name
grade
Type
string
Description
The assigned grade once available.
Name
result
Type
object
Description
Grade and quality metrics (protein, moisture, test weight, dockage). Null until grading is finalized.
Name
photos
Type
array
Description
Approved sample photos, each with a url and description.

Request

GET

/v1/me/inventory/:id/analysis

curl https://api.mygrainexchange.com/v1/me/inventory/inv_3Kd9/analysis \
  -H "Authorization: Bearer {token}"

Track progress with webhooks

Rather than poll, subscribe to the analysis lifecycle events on the Webhooks page: analysis.requested, analysis.sample_received, analysis.graded, and analysis.photo_added. They are delivered only to the team that requested the analysis.