# Month Performers

`GET` `https://api.unusualwhales.com/api/seasonality/{month}/performers`

Returns the tickers with the highest performance in terms of price change in the month over the years.
Per default the result is ordered by 'positive_months_perc' descending, then 'median_change' descending, then 'marketcap' descending.


## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `month` | SingleMonthNumber | Yes | A month number indicating the month, e.g. 1 -> January, 2 -> February, ... |

## Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `min_years` | Min Years | No | The minimum amount of years data for the month need to be available for the ticker. Default: 10. Min: 1. |
| `ticker_for_sector` | SingleTickerForSector | No | A single ticker. The result will only contain tickers in the same sector as the given ticker, e.g. 'MSFT' will only yield result tickers in sector 'Technology'. |
| `s_p_500_nasdaq_only` | Nasdaq Only | No |  |
| `min_oi` | Min Open Interest | No | The minimum open interest. Min: 0. |
| `limit` | Seasonality Performers Limit | No | How many items to return. Default: 50. Min: 1. |
| `order` | Seasonality Performance Order By | No | Optional columns to order the result by |
| `order_direction` | OrderDirection | No | Whether to sort descending or ascending. Descending by default. |


## Response (200)

| Field | Type | Description |
|-------|------|-------------|
| `avg_change` | Seasonality Average Change | The average relative price change per day for the month. |
| `marketcap` | Stock Marketcap AUM | The marketcap of the underlying ticker. If the issue type of the ticker is ETF then the marketcap represents the AUM. |
| `max_change` | Seasonality Max Change | The maximum relative price change per day for the month. |
| `median_change` | Seasonality Median Change | The median relative price change per day for the month. |
| `min_change` | Seasonality Min Change | The minimum relative price change per day for the month. |
| `month` | Seasonality Month Number | The number indicating the month the data applies for. e.g. 1 -> January, 2 -> February, ... |
| `positive_closes` | Seasonality Positive Closes Count | The number of years, the month had a positive close. |
| `positive_months_perc` | Seasonality Positive Months Percent | The relative amount of times, the month had a positive close. Multiply with 100 to get the amount in percent. |
| `sector` | Market General Sector | The financial sector of the ticker. Empty if unknown or not applicable such as ETF/Index. |
| `ticker` | Stock Ticker | The stock ticker. |
| `years` | Seasonality Year Count | The number of years used to calculate the data. |


## Example

### curl

```bash
curl -X GET "https://api.unusualwhales.com/api/seasonality/{month}/performers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Python

```python
import http.client

conn = http.client.HTTPSConnection("api.unusualwhales.com")
headers = {"Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json"}
conn.request("GET", "/api/seasonality/{month}/performers", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))
```

## Response Example

```json
{
  "data": [
    {
      "avg_change": "0.0592",
      "marketcap": "19427901578",
      "max_change": "0.1104",
      "median_change": "0.0639",
      "min_change": "0.0091",
      "month": 5,
      "positive_closes": 11,
      "positive_months_perc": "1.1",
      "sector": "Healthcare",
      "ticker": "ICLR",
      "years": 10
    },
    {
      "avg_change": "0.0577",
      "marketcap": "1927713687",
      "max_change": "0.2301",
      "median_change": "0.0417",
      "min_change": "-0.2485",
      "month": 5,
      "positive_closes": 10,
      "positive_months_perc": "1",
      "sector": "Technology",
      "ticker": "AMBA",
      "years": 10
    },
    {
      "avg_change": "0.0664",
      "marketcap": "60982620879",
      "max_change": "0.1791",
      "median_change": "0.07291",
      "min_change": "-0.0878",
      "month": 5,
      "positive_closes": 15,
      "positive_months_perc": "0.9375",
      "sector": "Healthcare",
      "ticker": "MCK",
      "years": 16
    },
    {
      "avg_change": "0.0674",
      "marketcap": "24233152429",
      "max_change": "0.2167",
      "median_change": "0.0723",
      "min_change": "-0.1812",
      "month": 5,
      "positive_closes": 15,
      "positive_months_perc": "0.9375",
      "sector": "Communication Services",
      "ticker": "TTWO",
      "years": 16
    }
  ]
}
```