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

> List crops belonging to farms owned by the authenticated user.

```
GET https://www.wiseyield.co/api/v1/crops
```

### Authentication

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

### Query parameters

<ParamField query="page" type="integer" default="1">
  Page number (≥ 1).
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Results per page (1–100; values above 100 are clamped to 100).
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `planned`, `planted`, `growing`, `harvested`, `failed`.
</ParamField>

<ParamField query="farmId" type="string">
  Filter to crops on a specific farm (UUID).
</ParamField>

<ParamField query="fieldId" type="string">
  Filter to crops on a specific field (UUID).
</ParamField>

<ParamField query="sort" type="string" default="createdAt">
  Sort field: `createdAt`, `cropType`, `plantedArea`, `plantingDate`.
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort direction: `asc`, `desc`.
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of crop objects.

  <Expandable title="Crop">
    <ResponseField name="id" type="string">UUID.</ResponseField>
    <ResponseField name="farmId" type="string">UUID of the parent farm.</ResponseField>
    <ResponseField name="fieldId" type="string">UUID of the field this crop is planted on. Required per the [Operations Attachment Principle](/concepts/land-hierarchy).</ResponseField>
    <ResponseField name="cropType" type="string">Free-text crop name (e.g. `"wheat"`, `"date palm"`).</ResponseField>
    <ResponseField name="variety" type="string | null">Free-text variety (e.g. `"Medjool"`).</ResponseField>
    <ResponseField name="adminCropId" type="string | null">UUID linking to the admin Crop Library (preferred over free-text).</ResponseField>
    <ResponseField name="adminCropVarietyId" type="string | null">UUID linking to the admin variety record.</ResponseField>
    <ResponseField name="plantedArea" type="string">Numeric string in the farm's `areaUnit`.</ResponseField>
    <ResponseField name="plantingDate" type="string | null">ISO 8601.</ResponseField>
    <ResponseField name="expectedHarvestDate" type="string | null">ISO 8601.</ResponseField>
    <ResponseField name="actualHarvestDate" type="string | null">ISO 8601. Auto-set when `status` transitions to `harvested`.</ResponseField>
    <ResponseField name="season" type="string | null">One of `winter`, `summer`, `autumn`, `spring`, `year_round`.</ResponseField>
    <ResponseField name="seasonYear" type="integer | null">e.g. `2026`.</ResponseField>
    <ResponseField name="expectedYield" type="string | null">Numeric string (tons).</ResponseField>
    <ResponseField name="actualYield" type="string | null">Numeric string (tons).</ResponseField>
    <ResponseField name="estimatedCost" type="string | null">Numeric string in the farm's `currency`.</ResponseField>
    <ResponseField name="actualCost" type="string | null">Numeric string in the farm's `currency`.</ResponseField>
    <ResponseField name="estimatedRevenue" type="string | null">Numeric string in the farm's `currency`.</ResponseField>
    <ResponseField name="actualRevenue" type="string | null">Numeric string in the farm's `currency`.</ResponseField>
    <ResponseField name="status" type="string">One of `planned`, `planted`, `growing`, `harvested`, `failed`.</ResponseField>
    <ResponseField name="notes" type="string | null">Free text, up to 5,000 characters.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination">
    <ResponseField name="page" type="integer">Echoes the requested page.</ResponseField>
    <ResponseField name="limit" type="integer">Page size applied.</ResponseField>
    <ResponseField name="total" type="integer">Total active records matching the query.</ResponseField>
    <ResponseField name="totalPages" type="integer">`Math.ceil(total / limit)`.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl 'https://www.wiseyield.co/api/v1/crops?status=growing&limit=50' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    'https://www.wiseyield.co/api/v1/crops?status=growing&limit=50',
    { headers: { Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}` } }
  );
  const { data, pagination } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.get(
      'https://www.wiseyield.co/api/v1/crops',
      params={'status': 'growing', 'limit': 50},
      headers={'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}"},
  )
  body = res.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "33333333-4444-5555-6666-777777777777",
        "farmId": "11111111-2222-3333-4444-555555555555",
        "fieldId": "88888888-9999-aaaa-bbbb-cccccccccccc",
        "cropType": "date palm",
        "variety": "Medjool",
        "adminCropId": null,
        "adminCropVarietyId": null,
        "plantedArea": "4.2",
        "plantingDate": "2024-03-15T00:00:00.000Z",
        "expectedHarvestDate": "2026-10-01T00:00:00.000Z",
        "actualHarvestDate": null,
        "season": "spring",
        "seasonYear": 2024,
        "expectedYield": "180",
        "actualYield": null,
        "estimatedCost": "12000",
        "actualCost": "10500",
        "estimatedRevenue": "45000",
        "actualRevenue": null,
        "status": "growing",
        "notes": "Drip-irrigated, fall NPK pending",
        "createdAt": "2024-03-15T08:00:00.000Z",
        "updatedAt": "2026-05-10T14:30:00.000Z"
      }
    ],
    "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": "Forbidden",
    "code": "INSUFFICIENT_SCOPE",
    "message": "Insufficient permissions. Required scope: crops:read",
    "details": {
      "requiredScope": "crops:read",
      "availableScopes": ["farms:read"]
    }
  }
  ```
</ResponseExample>

## Errors

| Status | When                                            |
| ------ | ----------------------------------------------- |
| `401`  | Missing, malformed, expired, or revoked API key |
| `403`  | Key lacks `crops:read` scope                    |
| `429`  | Rate limit reached                              |
| `5xx`  | Server error                                    |