API

To access this feature, send a request to [email protected]

API Access

Haystack provides API access for metrics. Below you can find the API endpoints and process of how to use them.

The API has two different endpoints for metrics. The first one is /metrics endpoint that supports global metrics. The second one is /teams/[teamId]/metrics and it’s for specific teams.

Haystack supports a number of different filters and metric types. Thus, to make things easier, we added support for copying any metric as a cURL request. Then, one can transform that into any language/environment.

Copy API Request Feature

In each metric in Haystack, you can find an option called Copy API Request . This function will give you the API cURL command to replicate the same behavior with the metric. We advise to use this feature, and then edit fields for your use case.

Authentication

Authentication done via Bearer tokens. To create a token, please go https://delivery.usehaystack.io/api-tokens page and create a token. Keep in mind that the tokens will only be available to copy after the token is created.

The token should be added as a header field. Example:

Authorization: Bearer YOUR_API_TOKEN

Requests

• Endpoint Host:

  • https://api.usehaystack.io

• Endpoint URL:

  1. POST /public/api/team/:teamId/metrics or POST /public/api/metrics

• Request Params

  • teamId: (Number) The ID of the team for which metrics are being requested. (Only exists if the endpoint is team endpoint)

• Request Body

  • startDate: (String) The start date of the metrics data range (format: YYYY-MM-DD).

  • endDate: (String) The end date of the metrics data range (format: YYYY-MM-DD).

  • granularity: (String) The granularity of the metrics data (week/month/cycle).

  • type: (String) The type of metrics data (issue/pull_request/cycle/deployment).

  • groupBy: (String) The parameter to group the metrics data by (team/author/assignee/epic, and more).

  • filters? : the filter array, we advise you to use the filter array given by our Copy API Request feature

Regular Responses

This responses are responses without groupBy and granularity selected as week or month. The responses include two different fields, data and averages.

• data : (Array) The metrics objects. Each object contains the following fields

  • title : (String) The title of the metric

  • measure : (String) Unique key of the metric

  • series : (Array) The values of the chart

    • x : (String) The x axis of the chart

    • value : (Number) The value

• averages : (Object) The averages of the results. This is used for Value chart types.

  • The averages object includes one or more then one fields. The name of the field depends on the request type.

  • The fields can be extracted from the measure field from the data . For instance if the measure is jiraIssue.count, then you should check for averages>jiraIssue>count for average of that metric.

Group By Responses

The structure of the group by responses are very similar to regular responses.

• data : (Array) The metrics objects. Each object contains the following fields

  • key (String) The unique key of the current groupby.

  • values (Array) The values for the metrics

    • title : (String) The title of the metric

    • measure : (String) Unique key of the metric

    • series : (Array) The values of the chart

      • x : (String) The x axis of the chart

      • value : (Number) The value

• averages : (Array) The averages of the results. This is used for Value chart types. Each item in the array exist for group by.

  • key (String) The unique key of the current groupby.

  • values (Array) The values for the metrics

    • The averages object includes one or more then one fields. The name of the field depends on the request type.

    • The fields can be extracted from the measure field from the data . For instance if the measure is jiraIssue.count, then you should check for averages>[number]>value>jiraIssue>count for average of that metric.

The rest of the fields in the response are for future use. You can ignore them for now.

Granularity Cycle Responses

When granularity selected as cycle, the response returns the cycles with analytics. Here is an example response:

{
    "data": [
        {
            "name": "Sprint 25",
            "state": "closed",
            "analytics": {
                "completionRate": "0.72727272727272727273",
                "storyPointCompletionRate": 0.6166666666666667,
                "issueCount": "22",
                "totalStoryPoints": 60,
                "injectedIssueCount": "9",
                "injectedStoryPoints": 16,
                "completedIssueCount": "16",
                "completedStoryPoints": 37,
                "committedIssueCount": "13",
                "committedStoryPoints": 44,
                "excludedIssueCount": "3",
                "excludedStoryPoints": 0,
                "removedIssueCount": "0",
                "removedStoryPoints": null
            }
        }
    ],
    "averages": {
        "cycle": {
            "completionRate": 0.803030303030303,
            "storyPointCompletionRate": 0.7670110192837466,
            "issueCount": 27.5,
            "totalStoryPoints": 60.25,
            "injectedIssueCount": 14,
            "injectedStoryPoints": 20.5,
            "completedIssueCount": 22.5,
            "completedStoryPoints": 46.25,
            "committedIssueCount": 13.5,
            "committedStoryPoints": 39.75,
            "excludedIssueCount": 1.5,
            "excludedStoryPoints": 0,
            "removedIssueCount": 0,
            "removedStoryPoints": 0
        }
    }
}

Rate Limits

20 requests per minute is allowed. After that, the system will give 429 as status code.

To increase this limit please contact [email protected].

Example

POST <https://api.usehaystack.io/public/api/metrics>
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
    "startDate": "2023-01-01",
    "endDate": "2023-01-31",
    "granularity": "month",
    "type": "issue",
    "groupBy": "author"
}