Skip to content
HamstikHamstik Docs

Project reports API

Project reports API

GET /api/v1/organizations/{organizationSlug}/projects/{projectKey}/reports/{reportType} returns one of Hamstik’s seven Project Reports:

velocity
cumulative-flow
control-chart
ageing-wip
created-vs-resolved
distribution
epic-progress

The endpoint requires a PAT with project:read, Organization membership, and access to the addressed Project. A Project in another Organization, or one that the caller cannot access, is returned as 404 NOT_FOUND without revealing whether it exists.

Terminal window
curl -H "Authorization: Bearer $HAMSTIK_TOKEN" \
  "https://hamstik.com/api/v1/organizations/$ORG_SLUG/projects/$PROJECT_KEY/reports/velocity?range=6"

Query parameters

All parameters are optional. limit is 1–100 and defaults to 50. cursor is the opaque cursor returned in page.nextCursor.

Parameter Reports Meaning
range velocity, time series Number of recent Sprint rows or requested calendar days. Created-vs-resolved supports 366 days; the other time series cap at 90, and every cap is reported.
start, end time series ISO calendar dates, interpreted in timeZone.
timeZone time series Valid IANA timezone for calendar boundaries.
unit velocity, cumulative-flow, distribution Velocity accepts points or items; the other reports accept count or points.
interval created-vs-resolved day, week, or month; weeks begin Monday.
measure control-chart cycle or lead.
cycleStartStatus control-chart Canonical status whose first entry starts cycle time.
window velocity, control-chart Rolling-average/statistics window.
groupBy distribution status, type, priority, assignee, or label.
scope distribution open or all.
sprint cumulative-flow, ageing-wip, created-vs-resolved, distribution Restrict the population to the Sprint ID.
sort epic-progress, ageing-wip Epic progress accepts name, progress, or targetDate; Ageing WIP accepts age, workItem, status, assignee, or since.
q, status, type, priority, assignee, label all applicable reports Work Item population filters.
squeakql all reports A validated SqueakQL population filter, combined with any simple filters.
buckets ageing-wip Ascending comma-separated inclusive day limits, such as 3,7,14,30,60.

Unknown or repeated scalar parameters return 400 VALIDATION_ERROR. The endpoint rejects malformed cursors with 400 INVALID_CURSOR and validates the report type before reading report data.

Response and pagination

The response contains the report-specific object plus items and data, which are the cursor-paginated rows for that report, and the standard page object. The full report metadata remains available alongside the page, including limitations, capped, and the canonical definition fields. page.nextCursor is null at the end; clients must treat the cursor as opaque.

CSV, SVG, and PNG are browser exports of the same serializable metric result; the API is JSON-only. Report definitions and edge-case behavior are described in Reports. The generated OpenAPI contract is authoritative for schemas, parameters, scopes, errors, and response details.

Stable metric rules

  • Velocity uses immutable Sprint commitments and excludes completion after a closed Sprint’s reporting boundary.
  • Flow values are end-of-day status snapshots reconstructed from history in the requested timezone.
  • Lead time is creation to final done; cycle time is first entry into the configured start status to final done. Currently reopened work is excluded.
  • Ageing is time in the current status and uses explicit inclusive buckets.
  • Resolved means the most recent transition into done; a later reopen returns the item to net open, so created, resolved, reopened, net, and cumulative-open values remain arithmetically consistent.
  • Distribution retains explicit None groups and reports a visible Other group when the group cap is reached.
  • Epic progress rolls up direct children only, in the addressed Project.