> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wiseyield.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Get yield prediction

> ML-based yield forecast with confidence intervals, trained on the farm's harvest history.

```
GET https://www.wiseyield.co/api/v1/farms/{id}/yield-prediction
```

Predicts the expected yield for a planned crop using a regression model trained on the farm's historical harvested + failed crops (last 50). Returns the predicted yield in tons along with p5/p50/p95 confidence intervals and the historical sample size used.

### Authentication

Requires a key with the `analytics:read` scope.

### Path parameters

<ParamField path="id" type="string" required>Farm UUID.</ParamField>

### Query parameters

<ParamField query="cropType" type="string" required>Crop name (e.g. `wheat`, `date palm`).</ParamField>

<ParamField query="plantedArea" type="number" required>Positive number in the farm's `areaUnit`.</ParamField>

<ParamField query="variety" type="string">Optional variety name (improves prediction accuracy when historical data exists for the same variety).</ParamField>

<ParamField query="season" type="string" default="year_round">`winter`, `summer`, `autumn`, `spring`, `year_round`.</ParamField>

<ParamField query="fieldId" type="string">Optional field UUID. When provided, the model uses the field's soil characteristics (overrides farm-level defaults).</ParamField>

### Response

<ResponseField name="data" type="object">
  <Expandable title="Prediction">
    <ResponseField name="predictedYield" type="number">Expected yield in tons.</ResponseField>

    <ResponseField name="confidenceIntervals" type="object">
      <Expandable title="CI">
        <ResponseField name="p5" type="number">5th percentile (pessimistic).</ResponseField>
        <ResponseField name="p50" type="number">Median.</ResponseField>
        <ResponseField name="p95" type="number">95th percentile (optimistic).</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trainingSampleSize" type="integer">Number of historical crops used to train the model.</ResponseField>
    <ResponseField name="modelConfidence" type="string">`high` · `moderate` · `low` — derived from sample size, soil-data completeness, and variance.</ResponseField>
    <ResponseField name="trustBadge" type="string">`data-driven` when the model had sufficient historical data + soil inputs; `data-assisted` when partial; `ai-generated` when the model fell back to defaults. See [Trust badges](/concepts/trust-badges).</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl 'https://www.wiseyield.co/api/v1/farms/11111111.../yield-prediction?cropType=wheat&plantedArea=50&season=winter' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ cropType: 'wheat', plantedArea: '50', season: 'winter' });
  const res = await fetch(
    `https://www.wiseyield.co/api/v1/farms/${farmId}/yield-prediction?${params}`,
    { headers: { Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}` } }
  );
  const { data: prediction } = await res.json();
  console.log('Predicted yield:', prediction.predictedYield, 'tons');
  console.log('95% CI:', prediction.confidenceIntervals.p5, '-', prediction.confidenceIntervals.p95);
  ```

  ```python Python theme={null}
  import os, requests
  res = requests.get(
      f'https://www.wiseyield.co/api/v1/farms/{farm_id}/yield-prediction',
      params={'cropType': 'wheat', 'plantedArea': 50, 'season': 'winter'},
      headers={'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}"},
  )
  prediction = res.json()['data']
  ```
</RequestExample>

## Errors

| Status                    | When                                                               |
| ------------------------- | ------------------------------------------------------------------ |
| `400 VALIDATION_ERROR`    | Missing `cropType` or `plantedArea`, or `plantedArea` not positive |
| `400 INVALID_ID`          | `{id}` or `fieldId` is not a valid UUID                            |
| `401`                     | Missing, malformed, expired, or revoked API key                    |
| `403 INSUFFICIENT_SCOPE`  | Key lacks `analytics:read` scope                                   |
| `404 NOT_FOUND`           | Farm doesn't exist or belongs to another user                      |
| `429 RATE_LIMIT_EXCEEDED` | Per-user rate limit reached                                        |
| `5xx`                     | Server error                                                       |

## Notes

* The model needs at least 3 historical harvested/failed crops of the same `cropType` for `data-driven` accuracy. Fewer historical crops drops the `trustBadge` to `data-assisted` or `ai-generated`.
* See [Trust badges](/concepts/trust-badges) for the integrity contract.