Skip to main content

Milestones

The milestones namespace provides API methods to retrieve milestones for a project. The following endpoints are available:

GET /projects/{project_id}/milestones

Returns all milestones for a project.

This method uses pagination so you might need to request additional pages to retrieve all milestones.

project_id id required
ID of the project.
 

Request

Parameters
Schema

page integer
Number of page to return (default: first page).
 

per_page integer
Maximum number of milestones to return (supported: 15, 25, 50, 100; default: 100).
 

sort string
Sort field for the list of milestones (supported: milestones:created_at, milestones:completed_at; default: milestones:created_at).
 

order string
Sort order (supported: asc, desc; default: desc).
 

name string
Filter milestones by name (partial match).
 

type_id string
Comma-separated list of milestone type IDs to filter by.
 

is_completed boolean
Limit results to active (false) or completed (true) milestones only.
 

parent_id string
Comma-separated list of parent milestone IDs to filter by.
 

root_id string
Comma-separated list of root milestone IDs to filter by.
 

created_after string
Limit results to milestones created after this date/time (ISO 8601, UTC).
 

created_before string
Limit results to milestones created before this date/time (ISO 8601, UTC).
 

created_by string
Comma-separated list of user IDs to filter by creator.
 

completed_after string
Limit results to milestones completed after this date/time (ISO 8601, UTC).
 

completed_before string
Limit results to milestones completed before this date/time (ISO 8601, UTC).
 

starts_after string
Limit results to milestones with a start date on or after this date/time (ISO 8601, UTC).
 

starts_before string
Limit results to milestones with a start date on or before this date/time (ISO 8601, UTC).
 

due_from string
Limit results to milestones with a due date on or after this date/time (ISO 8601, UTC).
 

due_to string
Limit results to milestones with a due date on or before this date/time (ISO 8601, UTC).
 

automation_tags string
Comma-separated list of automation tag names to filter by.
 

expands string
Comma-separated list of expands to return.
  

{
  "page": {
      "type": "integer",
      "format": "int64",
      "description": "Number of page to return (default: first page)."
  },
  "per_page": {
      "type": "integer",
      "format": "int64",
      "enum": [15, 25, 50, 100],
      "description": "Maximum number of items to return per page (default: 100)."
  },
  "sort": {
      "type": "string",
      "enum": ["milestones:created_at", "milestones:completed_at"],
      "default": "milestones:created_at",
      "description": "Sort field for the list of milestones."
  },
  "order": {
      "type": "string",
      "enum": ["asc", "desc"],
      "default": "desc",
      "description": "Sort order (ascending or descending)."
  },
  "name": {
      "type": "string",
      "description": "Filter milestones by name (partial match)."
  },
  "type_id": {
      "type": "string",
      "description": "Comma-separated list of milestone type IDs to filter by."
  },
  "is_completed": {
      "type": "boolean",
      "description": "Limit results to active (false) or completed (true) milestones only."
  },
  "parent_id": {
      "type": "string",
      "description": "Comma-separated list of parent milestone IDs to filter by."
  },
  "root_id": {
      "type": "string",
      "description": "Comma-separated list of root milestone IDs to filter by."
  },
  "created_after": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to milestones created after this date/time (ISO 8601, UTC)."
  },
  "created_before": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to milestones created before this date/time (ISO 8601, UTC)."
  },
  "created_by": {
      "type": "string",
      "description": "Comma-separated list of user IDs to filter by creator."
  },
  "completed_after": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to milestones completed after this date/time (ISO 8601, UTC)."
  },
  "completed_before": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to milestones completed before this date/time (ISO 8601, UTC)."
  },
  "starts_after": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to milestones with a start date on or after this date/time (ISO 8601, UTC)."
  },
  "starts_before": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to milestones with a start date on or before this date/time (ISO 8601, UTC)."
  },
  "due_from": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to milestones with a due date on or after this date/time (ISO 8601, UTC)."
  },
  "due_to": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to milestones with a due date on or before this date/time (ISO 8601, UTC)."
  },
  "automation_tags": {
      "type": "string",
      "description": "Comma-separated list of automation tag names to filter by."
  },
  "expands": {
      "type": "string",
      "description": "Comma-separated list of expands to return (issues, milestone_stats, milestone_types, milestones, statuses, users)."
  }
}

This method supports the following expands so you can automatically include additional information for referenced objects:

  • issues
  • milestone_stats
  • milestone_types
  • milestones
  • statuses
  • users

Response

GET /api/v1/projects/1/milestones

 
200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        {
            "id": 1,
            "project_id": 1,
            "root_id": null,
            "parent_id": null,
            "type_id": 1,
            "name": "v2.0 Release",
            "note": "Q3 release",
            "is_started": true,
            "is_completed": false,
            "start_date": null,
            "due_date": "2025-09-30",
            "automation_tags": [],
            "issues": [],
            "links": [],
            "started_at": "2025-07-01T00:00:00.000000Z",
            "created_at": "2025-06-15T10:22:00.000000Z",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null,
            "completed_at": null
        },
        ..
    ],
    "expands": {}
}

Examples

// Get all milestones for a project
GET /api/v1/projects/1/milestones

// Filter by name (partial match)
GET /api/v1/projects/1/milestones?name=release

// Get active milestones only
GET /api/v1/projects/1/milestones?is_completed=false

// Get completed milestones ordered by completion date
GET /api/v1/projects/1/milestones?is_completed=true&sort=milestones:completed_at

// Filter by milestone type
GET /api/v1/projects/1/milestones?type_id=1,2

// Filter milestones with a due date in a range
GET /api/v1/projects/1/milestones?due_from=2025-07-01&due_to=2025-09-30

// Filter by creation date
GET /api/v1/projects/1/milestones?created_after=2025-01-01T00:00:00Z

// Include milestone type and user expands
GET /api/v1/projects/1/milestones?expands=milestone_types,users

// Paginate through results
GET /api/v1/projects/1/milestones?page=2&per_page=50

Status codes

200 401 403 422 429 (details)

GET /milestones/{milestone_id}

Returns a single milestone.

milestone_id id required
ID of the milestone.
 

Request

Parameters
Schema

expands string
Comma-separated list of expands to return.
  

{
  "expands": {
      "type": "string",
      "description": "Comma-separated list of expands to return (issues, milestone_stats, milestone_types, milestones, statuses, users)."
  }
}

This method supports the following expands so you can automatically include additional information for referenced objects:

  • issues
  • milestone_stats
  • milestone_types
  • milestones
  • statuses
  • users

Response

GET /api/v1/milestones/1

 
200 OK
{
    "result": {
        "id": 1,
        "project_id": 1,
        "root_id": null,
        "parent_id": null,
        "type_id": 1,
        "name": "v2.0 Release",
        "note": "Q3 release",
        "is_started": true,
        "is_completed": false,
        "start_date": null,
        "due_date": "2025-09-30",
        "automation_tags": [],
        "issues": [],
        "links": [],
        "started_at": "2025-07-01T00:00:00.000000Z",
        "created_at": "2025-06-15T10:22:00.000000Z",
        "created_by": 2,
        "updated_at": null,
        "updated_by": null,
        "completed_at": null
    },
    "expands": {}
}

Examples

// Get milestone with ID 1
GET /api/v1/milestones/1

// Include milestone type and user expands
GET /api/v1/milestones/1?expands=milestone_types,users

Status codes

200 401 403 404 429 (details)

GET /projects/{project_id}/milestone-types

Returns the list of milestone types configured for the specified project. Use this endpoint to retrieve valid type IDs for use when filtering milestones.

project_id id required
ID of the project.
 

Response

GET /api/v1/projects/1/milestone-types

 
200 OK
{
    "result": [
        {
            "id": 1,
            "name": "Release",
            "is_default": true
        },
        {
            "id": 2,
            "name": "Sprint",
            "is_default": false
        },
        {
            "id": 3,
            "name": "Phase",
            "is_default": false
        }
    ]
}

Status codes

200 401 403 404 429 (details)

Was this article helpful?