# API

{% hint style="info" %}
To access this feature, send a request to [support@usehaystack.io ](mailto:support@usehaystack.io)
{% endhint %}

## 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.

<figure><img src="https://933147321-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbiIqB8vq91hNrILQ1MAF%2Fuploads%2F6OfZwY7gcJntmmwQb5Zx%2F825152f939266854ac5c7093057d286e.png?alt=media&#x26;token=1796179f-103c-44cb-ab5d-6ce3c4270a20" alt=""><figcaption></figcaption></figure>

<figure><img src="https://933147321-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbiIqB8vq91hNrILQ1MAF%2Fuploads%2FhWNqqxWCcCEeAQR5T0pg%2Fc78a76194c1ed91626a896b495c7c107.png?alt=media&#x26;token=ac2e12ed-4075-4d07-9a76-eb5907b59c3e" alt=""><figcaption></figcaption></figure>

### 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.

<figure><img src="https://933147321-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbiIqB8vq91hNrILQ1MAF%2Fuploads%2FkO0Zi27lKfZoGor3fLBX%2FScreenshot%202024-06-21%20at%2013.06.22.png?alt=media&#x26;token=93386fa5-e8ee-46c9-a017-432eddccde13" alt=""><figcaption></figcaption></figure>

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

```jsx
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 <support@usehaystack.io>.

### Example

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

<br>