> For the complete documentation index, see [llms.txt](https://help.tahua.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tahua.io/knowledge-base/integrations-help-guides/api-access/api-reference/milestones.md).

# Milestones

## GET /api/v2/milestones

Returns a list of milestones with their deliverable data.

### Query Parameters

| Parameter | Type    | Description                                    |
| --------- | ------- | ---------------------------------------------- |
| `limit`   | integer | Results per page (default: 50, max: 50)        |
| `gt`      | integer | Return records with ID greater than this value |
| `lt`      | integer | Return records with ID less than this value    |

### Filtering

Milestones can be filtered by deliverable data and by specific IDs.

#### Filter by deliverable values

```
GET /api/v2/milestones?filters[deliverables][value]=Smith
```

Use `%` as a wildcard for partial matching:

```
GET /api/v2/milestones?filters[deliverables][value]=%Smith%
```

#### Filter by deliverable field tags

Filter by the `internal_identifier` of deliverable fields:

```
GET /api/v2/milestones?filters[deliverables][tags][]=artist_name&filters[deliverables][tags][]=song_title
```

Or combine a tag with a value to search within a specific field:

```
GET /api/v2/milestones?filters[deliverables][tag]=artist_name&filters[deliverables][value]=Smith
```

#### Filter by IDs

```
GET /api/v2/milestones?filters[ids][]=1&filters[ids][]=2&filters[ids][]=3
```

### Response Properties

| Property         | Type     | Description                       |
| ---------------- | -------- | --------------------------------- |
| `id`             | integer  | Unique identifier                 |
| `created_at`     | datetime | When the record was created       |
| `updated_at`     | datetime | When the record was last updated  |
| `title`          | string   | Milestone title                   |
| `contract_id`    | integer  | ID of the associated contract     |
| `funding_amount` | decimal  | Funding amount for this milestone |
| `description`    | string   | Milestone description             |
| `state`          | string   | Current milestone state           |
| `paid_at`        | datetime | When the milestone was paid       |
| `decline_reason` | string   | Reason for decline (if declined)  |
| `due_date`       | date     | Milestone due date                |
| `contract.id`    | integer  | Contract ID                       |
| `contract.title` | string   | Contract title                    |

#### Deliverables

Each milestone includes a `deliverables_template_entry` object containing form inputs:

| Property                                                         | Type    | Description              |
| ---------------------------------------------------------------- | ------- | ------------------------ |
| `deliverables_template_entry.id`                                 | integer | Entry ID                 |
| `deliverables_template_entry.inputs[].id`                        | integer | Input ID                 |
| `deliverables_template_entry.inputs[].value`                     | string  | Input value              |
| `deliverables_template_entry.inputs[].file`                      | object  | File attachment metadata |
| `deliverables_template_entry.inputs[].tahua_file_url`            | string  | URL to download the file |
| `deliverables_template_entry.inputs[].field.id`                  | integer | Field ID                 |
| `deliverables_template_entry.inputs[].field.internal_identifier` | string  | Field identifier         |

### Example Request

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-org.tahua.io/api/v2/milestones?limit=10"
```

### Example Response

```json
[
  {
    "id": 15,
    "created_at": "2025-05-01T09:00:00.000Z",
    "updated_at": "2025-05-20T14:00:00.000Z",
    "title": "Progress Report 1",
    "contract_id": 8,
    "funding_amount": "12500.0",
    "description": "First progress report and deliverables",
    "state": "approved",
    "paid_at": "2025-06-01T10:00:00.000Z",
    "decline_reason": null,
    "due_date": "2025-09-30",
    "contract": {
      "id": 8,
      "title": "Community Arts Programme - Contract"
    },
    "deliverables_template_entry": {
      "id": 22,
      "created_at": "2025-05-01T09:00:00.000Z",
      "updated_at": "2025-05-18T16:00:00.000Z",
      "inputs": [
        {
          "id": 101,
          "created_at": "2025-05-18T16:00:00.000Z",
          "updated_at": "2025-05-18T16:00:00.000Z",
          "value": "Workshop completed with 30 participants",
          "file": null,
          "tahua_file_url": null,
          "field": {
            "id": 50,
            "created_at": "2025-01-01T00:00:00.000Z",
            "updated_at": "2025-01-01T00:00:00.000Z",
            "internal_identifier": "workshop_summary"
          }
        }
      ]
    }
  }
]
```

***

## GET /api/v2/milestones/:id

Returns a single milestone. Response properties are the same as the list endpoint.

### Example Request

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-org.tahua.io/api/v2/milestones/15"
```