# Macro Series

`GET` `/v1/macro`

Retrieve macroeconomic time series stored by Vantafin. Call without a category to list available categories (e.g. treasury rates, central bank policy). With a category, returns series keys, as-of dates, numeric values and optional payload JSON for each observation - ideal for rates dashboards, macro context on research pages and tying equity analysis to the interest-rate environment.

## Use cases

- Central bank and Treasury rate dashboards
- Macro context alongside equity research
- Economic indicator charts and alerts
- Risk models that need policy-rate or yield inputs

## Input parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | string | No | Macro category; omit to list categories. |
| `limit` | integer | No | Max rows (default 500). |

## Output parameters

| Name | Type | Description |
| --- | --- | --- |
| `results` | array | Macro observations or category listing rows. |
| `results[].category` | string | Macro category key (e.g. treasury_rates). |
| `results[].series_key` | string | Series identifier within the category. |
| `results[].as_of_date` | string | Observation date (YYYY-MM-DD). |
| `results[].numeric_value` | float | Primary numeric value for the series. |
| `results[].payload` | object | Additional structured fields for the observation. |
| `results[].updated_at` | string | Last update timestamp (ISO 8601). |
| `count` | integer | Number of rows returned. |

## Example response

```json
{
  "results": [
    {
      "category": "treasury_rates",
      "series_key": "",
      "as_of_date": "2026-06-05",
      "numeric_value": null,
      "payload": {
        "year1": 3.88,
        "year2": 4.17,
        "year3": 4.22,
        "year5": 4.29,
        "year7": 4.41,
        "month1": 3.71,
        "month2": 3.71,
        "month3": 3.78,
        "month6": 3.81,
        "year10": 4.55,
        "year20": 5.03,
        "year30": 5.01
      },
      "updated_at": "2026-06-06T02:00:00.283756+00:00"
    },
    {
      "category": "treasury_rates",
      "series_key": "",
      "as_of_date": "2026-06-04",
      "numeric_value": null,
      "payload": {
        "year1": 3.82,
        "year2": 4.05,
        "year3": 4.1,
        "year5": 4.18,
        "year7": 4.32,
        "month1": 3.71,
        "month2": 3.7,
        "month3": 3.78,
        "month6": 3.78,
        "year10": 4.47,
        "year20": 4.98,
        "year30": 4.97
      },
      "updated_at": "2026-06-06T02:00:00.286453+00:00"
    }
  ],
  "count": 500
}
```

## Examples

### cURL

```bash
curl "https://api.vantafin.com/v1/macro?category=treasury_rates&apiKey=$VANTAFIN_API_KEY"
```

### Python

```python
from vantafin import RESTClient

client = RESTClient("vf-live-your_api_key")

result = client.get_macro(category="treasury_rates")

print(result)
```

### JavaScript

```javascript
import { RestClient } from "vantafin";

const client = new RestClient("vf-live-your_api_key");

const result = await client.getMacro({ category: "treasury_rates" });

console.log(result);
```

### Go

```go
package main

import (
	"fmt"
	"log"

	"github.com/vantafin/vantafin-go"
)

func main() {
	client := vantafin.NewClient("vf-live-your_api_key")

	result, err := client.GetMacro(vantafin.Params{"category": "treasury_rates"})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result)
}
```

### Java

```java
import com.vantafin.RestClient;
import com.vantafin.Params;

public class Example {
    public static void main(String[] args) throws Exception {
        RestClient client = new RestClient("vf-live-your_api_key");

        Object result = client.getMacro(Params.of().set("category", "treasury_rates"));

        System.out.println(result);
    }
}
```

### Ruby

```ruby
require "vantafin"

client = Vantafin::RestClient.new("vf-live-your_api_key")

result = client.get_macro(category: "treasury_rates")

pp result
```