list_milestones

Discover milestone titles and states before narrowing an issue search. Every call targets one authorized repository and leaves its issues unchanged.

Parameters

Example call

list_milestones({
  "repo": "acme/sdk",
  "state": "open",
  "limit": 50
})

Example response

{
  "repo": "acme/sdk",
  "milestones": [
    {
      "title": "v2.0",
      "state": "open",
      "description": "Stability fixes for the next major release."
    },
    {
      "title": "v2.1",
      "state": "open",
      "description": "Follow-up reliability improvements."
    }
  ],
  "returned_count": 2,
  "truncated": false
}

Limits and edge cases

Milestone state and issue state are separate fields. An open issue can be assigned to a closed milestone. Use the returned title exactly for search_issues.milestone; this input takes a title, not a milestone ID.

The response includes title, state and description. It does not promise a due date, progress percentage or completion estimate. The fixture orders milestones by title.

An empty list is valid. Unsupported state or an invalid limit yields INVALID_ARGUMENT. A truncated catalog has no defined continuation in this contract; do not invent an offset.

Errors and recovery

AUTH_REQUIRED means the credential is missing or no longer valid. ACCESS_DENIED means it cannot read the repository. INVALID_ARGUMENT means an input violates this schema. RATE_LIMITED and UPSTREAM_UNAVAILABLE need an upstream recovery step, not a broader permission grant.

Full error reference

Authentication and scope