> ## 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.

# List fields

> List fields on a farm.

```
GET https://www.wiseyield.co/api/v1/farms/{id}/fields
```

### Authentication

Requires a key with the `fields:read` scope. See [Authentication](/authentication).

### Path parameters

<ParamField path="id" type="string" required>
  Farm UUID. Must be a farm owned by the authenticated user.
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of field objects scoped to the farm. Soft-deleted fields are excluded.

  <Expandable title="Field">
    <ResponseField name="id" type="string">UUID.</ResponseField>
    <ResponseField name="farmId" type="string">UUID of the parent farm.</ResponseField>
    <ResponseField name="name" type="string">Field name.</ResponseField>
    <ResponseField name="description" type="string | null">Free-text description.</ResponseField>
    <ResponseField name="area" type="string">Numeric string in the farm's `areaUnit`.</ResponseField>
    <ResponseField name="boundaries" type="object | null">GeoJSON `Polygon` for the field perimeter.</ResponseField>
    <ResponseField name="soilType" type="string | null">Free-text soil description.</ResponseField>
    <ResponseField name="soilPh" type="string | null">pH as numeric string.</ResponseField>
    <ResponseField name="status" type="string">One of `active`, `fallow`, `preparing`, `planted`.</ResponseField>
    <ResponseField name="currentCropId" type="string | null">Active crop on this field (if any).</ResponseField>
    <ResponseField name="notes" type="string | null">Free text, up to 5,000 characters.</ResponseField>
    <ResponseField name="irrigationFlowRatePerEmitter" type="string | null">Liters/hour per emitter (Blueprint §9.4).</ResponseField>
    <ResponseField name="emittersPerPlant" type="integer | null">Emitter count per plant.</ResponseField>
    <ResponseField name="dripLineSpacingMeters" type="string | null">Drip-line spacing in meters.</ResponseField>
    <ResponseField name="customIrrigationSystem" type="string | null">One of `drip`, `sprinkler`, `flood`, `pivot`, `manual`, `none` — overrides farm default.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl 'https://www.wiseyield.co/api/v1/farms/11111111-2222-3333-4444-555555555555/fields' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    `https://www.wiseyield.co/api/v1/farms/${farmId}/fields`,
    { headers: { Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}` } }
  );
  const { data: fields } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests
  res = requests.get(
      f'https://www.wiseyield.co/api/v1/farms/{farm_id}/fields',
      headers={'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}"},
  )
  fields = res.json()['data']
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "88888888-9999-aaaa-bbbb-cccccccccccc",
        "farmId": "11111111-2222-3333-4444-555555555555",
        "name": "North Field",
        "area": "4.2",
        "boundaries": { "type": "Polygon", "coordinates": [[[31.2,30.0],[31.3,30.0],[31.3,30.1],[31.2,30.1],[31.2,30.0]]] },
        "soilType": "sandy loam",
        "soilPh": "7.2",
        "status": "active",
        "currentCropId": "33333333-4444-5555-6666-777777777777",
        "createdAt": "2024-03-15T08:00:00.000Z",
        "updatedAt": "2026-05-10T14:30:00.000Z"
      }
    ]
  }
  ```

  ```json 404 Farm not found theme={null}
  { "error": "Not found", "code": "NOT_FOUND", "message": "Farm not found" }
  ```
</ResponseExample>

## Errors

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