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

> List blocks on a field. Blocks are variety/management cohorts inside a field.

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

See [Land hierarchy](/concepts/land-hierarchy) for when to use blocks vs field-level only.

### Authentication

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

### Path parameters

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

### Query parameters

<ParamField query="status" type="string">
  Filter by block status: `planned`, `planted`, `established`, `mature`, `declined`, `harvested`, `removed`.
</ParamField>

<ParamField query="cropId" type="string">
  Filter to blocks of a specific crop (UUID).
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of block objects. Soft-deleted blocks are excluded.

  <Expandable title="Block">
    <ResponseField name="id" type="string">UUID.</ResponseField>
    <ResponseField name="cropId" type="string">UUID of the parent crop.</ResponseField>
    <ResponseField name="fieldId" type="string">UUID of the parent field.</ResponseField>
    <ResponseField name="varietyId" type="string | null">UUID linking to admin variety record (pulls spacing/density defaults).</ResponseField>
    <ResponseField name="name" type="string">Block name (e.g. "North block — Siwi").</ResponseField>
    <ResponseField name="description" type="string | null">Free text.</ResponseField>
    <ResponseField name="plantingDate" type="string | null">ISO 8601.</ResponseField>
    <ResponseField name="plantCount" type="integer | null">Total plant count in the block.</ResponseField>
    <ResponseField name="spacingX" type="string | null">Row spacing in meters (numeric string).</ResponseField>
    <ResponseField name="spacingY" type="string | null">Plant spacing in meters (numeric string).</ResponseField>
    <ResponseField name="plantDensity" type="string | null">Plants per hectare (numeric string).</ResponseField>
    <ResponseField name="area" type="string | null">Block area (numeric string).</ResponseField>
    <ResponseField name="geometry" type="object | null">GeoJSON `Polygon` or `Point`.</ResponseField>
    <ResponseField name="plantingGrid" type="object | null">Grid metadata (`{ pattern, rowCount, columnCount, rowOrientation, originLatLng }`).</ResponseField>
    <ResponseField name="status" type="string">One of `planned`, `planted`, `established`, `mature`, `declined`, `harvested`, `removed`.</ResponseField>
    <ResponseField name="notes" type="string | null">Free text.</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.../fields/88888888.../blocks?status=mature' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY"
  ```

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

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

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "cropId": "33333333-4444-5555-6666-777777777777",
        "fieldId": "88888888-9999-aaaa-bbbb-cccccccccccc",
        "name": "North block — Medjool",
        "plantCount": 60,
        "spacingX": "10",
        "spacingY": "10",
        "plantDensity": "100",
        "area": "0.6",
        "status": "mature",
        "createdAt": "2024-03-15T08:00:00.000Z",
        "updatedAt": "2026-05-10T14:30:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>

## Errors

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