Help Center
Help Center
  • Getting Started
    • What is Haystack?
    • Quick Start
      • Account Setup
      • Roles
        • For Executives
        • For Managers
        • For Product
  • Setup
    • Integrations
      • Jira
      • GitHub Cloud
      • GitHub Enterprise
      • GitLab
      • Bitbucket
      • Slack
    • Organization
      • Investments
      • Deployments
      • Invite users
      • Exclusions
    • Teams
      • Map members
      • Sprint success metric
      • Capacity
      • Alerts
      • SLAs
      • Risks
  • Features
    • Issues
    • Pull Requests
    • Epics
    • Retrospective
    • Release Notes
    • Investments
    • Alerts
    • Customizable Widgets
    • Flexible Reports
    • Team Metrics
    • List of All Metrics
    • API
    • Embedded reports
  • Admin
    • Security & Privacy
    • Data Sync
      • How to setup faster data sync for JIRA?
  • FAQ
    • Can I track Dora metrics?
    • What is Status Category?
  • Guides
    • First Principles of Engineering Metrics
    • Engineering Metrics (Video Series)
    • How to Improve Quality?
    • Sprint Planning
    • Daily Standups
    • Retrospectives
    • Identify Bottlenecks
  • Other
    • Changelog
Powered by GitBook
On this page
  • API Access
  • Copy API Request Feature
  • Authentication
  • Requests
  • Regular Responses
  • Granularity Cycle Responses
  • Rate Limits
  • Example

Was this helpful?

  1. Features

API

Last updated 11 months ago

Was this helpful?

To access this feature, send a request to

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

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.

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"
}

Authentication done via Bearer tokens. To create a token, please go page and create a token. Keep in mind that the tokens will only be available to copy after the token is created.

To increase this limit please contact .

https://delivery.usehaystack.io/api-tokens
support@usehaystack.io
support@usehaystack.io