neosourceDocs
Search docs

List cycles for a team (most recent first)

GET/api/teams/{team_id}/cycles

listCycles

Cycles are internal team planning data; the actor must be a member of the team.

Requires authentication using a bearer token or a session cookie — see tokens and scopes.

curl

curl -X GET 'https://neosource.dev/api/teams/TEAM_ID/cycles' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN'

fetch

fetch("https://neosource.dev/api/teams/TEAM_ID/cycles", {
  method: "GET",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
  },
});

Path parameters

team_idrequired

string

Responses

200Cycle list

application/json

CycleListResponse

object

cyclesrequired

array

items

CycleResponse

object

completed_at

integer | nullint64

created_atrequired

integerint64

cycle_idrequired

string

ends_atrequired

integerint64

initiative_id

string | null

namerequired

string

progressrequired
CycleProgressResponse
starts_atrequired

integerint64

team_idrequired

string

403Forbidden — one of: forbidden, needs_scope

application/json

one of
  • ErrorForbidden

  • NeedsScopeError

    object

    `403` body returned when listing private repos but the linked identity lacks the required provider scope. The SPA turns this into an incremental-authorization prompt (Tier 2) that calls the `/elevate` OAuth endpoint with this `scope`.

    errorrequired

    string

    Always `needs_scope` — this body exists to carry the extra fields that kind needs.

    "needs_scope"

    scoperequired

    string

    The provider scope to request via elevation (e.g. `"repo"`).

Standard errors

Bodies documented once for the whole API — see standard errors.

  • 400Bad Request — one of: invalid_input
  • 401Authentication required
  • 404Not Found — one of: not_found
  • 429Rate limited — retry after the `Retry-After` header
  • 500Internal server error
  • 503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
  • 504Gateway timeout — the request exceeded the server's handling budget

Schemas

Referenced above. Listed here rather than expanded inline, so the same definition is not repeated at every level.

CycleProgressResponse

object

How much work a cycle holds and how far through it the team is. Present on EVERY cycle payload, not just the listing: a surface that has a cycle in hand should never have to ask a second endpoint whether it contains anything. The four numbers are computed over one set — every live issue bound to the cycle — which is the same set the cycle's issue listing returns and the same set completing the cycle carries over, so a progress bar can never describe a different cycle from the rows under it. `started` and `blocked` overlap each other and both sit inside `total - done`; they are two views of the unfinished remainder rather than a partition, and are reported as such.

blockedrequired

integerint64

...flagged blocked and unfinished.

donerequired

integerint64

...in a terminal status (`done` / `cancelled` / `duplicate`).

startedrequired

integerint64

...started and unfinished: `in_progress` or `in_review`.

totalrequired

integerint64

Live issues bound to this cycle.