# Providers

> Provider-scoped reads for recommendations, savings, and costs on AWS, GCP, Azure, and Kubernetes. A provider you have not connected returns 404.

Source: https://docs.levelfour.ai/resources/providers


These methods read recommendations, savings and costs for one cloud at a time. The provider IDs are `aws`, `gcp`, `azure` and `k8s`, and every method except [List providers](#list-providers) takes one.

> **Note**
>
> Only [List providers](#list-providers) lives on `client.providers`. That namespace has exactly one method. Everything else on this page is grouped by what it reads, not by where it lives, so the calls sit on `client.recommendations` and `client.costs` and take a provider ID as their first argument.

A provider carries data only once you have [connected it](/quickstart).

> **Error**
>
> A provider your organization has not connected returns `404` on every provider-scoped path below. Call [List providers](#list-providers) first rather than assuming an ID is available.

## List providers

Returns all configured cloud providers for your account.

**Python**

```python  
providers = client.providers.list()
```

**TypeScript**

```typescript  
const providers = await client.providers.list();
```

**Go**

```go  
providers, err := client.Providers.List(ctx)
```

## Recommendations

### Get top recommendations

Returns the top 7 recommendations for a specific provider, sorted by savings.

**Python**

```python  
top = client.recommendations.get_top("aws")
```

**TypeScript**

```typescript  
const top = await client.recommendations.getTop({ provider_id: "aws" });
```

**Go**

```go  
top, err := client.Recommendations.GetTop(ctx, "aws")
```

### List recommendations

Returns a paginated, filterable list of recommendations for a provider.

**Python**

```python  
page = client.recommendations.list_by_provider(
    "aws",
    page=1,
    page_size=50,
    sort_by="monthly_savings",
    sort_order="desc",
    service=["EC2", "RDS"],
    environment=["production"],
    display_status=["available", "pending"],
)

for rec in page:
    print(f"{rec.recommendation_id}: ${rec.monthly_savings}/mo")
```

**TypeScript**

```typescript  
for await (const rec of await client.recommendations.listByProvider({
    provider_id: "aws",
    page_size: 50,
    sort_by: "monthly_savings",
    sort_order: "desc",
    service: ["EC2", "RDS"],
    display_status: ["available", "pending"],
})) {
    console.log(`${rec.recommendation_id}: $${rec.monthly_savings}/mo`);
}
```

**Go**

```go  
page, err := client.Recommendations.ListByProvider(ctx, "aws",
    &levelfour.ListByProviderRecommendationsRequest{
        PageSize:      levelfour.Int(50),
        SortBy:        levelfour.String("monthly_savings"),
        SortOrder:     levelfour.ListByProviderRecommendationsRequestSortOrder("desc").Ptr(),
        Service:       []string{"EC2", "RDS"},
        DisplayStatus: []string{"available", "pending"},
    },
)
```

#### Parameters

| Parameter           | Type       | Description                                                                                                                    |
| ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `provider_id`       | `string`   | Provider: `aws`, `gcp`, `azure`, `k8s`                                                                                         |
| `start`             | `string`   | Start date (ISO 8601: `YYYY-MM-DD`)                                                                                            |
| `end`               | `string`   | End date (ISO 8601: `YYYY-MM-DD`)                                                                                              |
| `page`              | `int`      | Page number (1-indexed)                                                                                                        |
| `page_size`         | `int`      | Items per page                                                                                                                 |
| `sort_by`           | `string`   | Sort field: `recommendation_id`, `service`, `environment`, `account`, `tag`, `monthly_savings`, `savings_percentage`, `status` |
| `sort_order`        | `string`   | `asc` or `desc`                                                                                                                |
| `service`           | `string[]` | Filter by service(s)                                                                                                           |
| `environment`       | `string[]` | Filter by environment(s)                                                                                                       |
| `account`           | `string[]` | Filter by account(s)                                                                                                           |
| `tag`               | `string[]` | Filter by tag(s)                                                                                                               |
| `virtual_tag_key`   | `string`   | A virtual tag's name or id. Keeps the opportunities whose resources carry one of `virtual_tag_value` under it                  |
| `virtual_tag_value` | `string[]` | Values of `virtual_tag_key` to keep. `__unallocated__` keeps the opportunities no config assigned                              |
| `display_status`    | `string[]` | Filter by status: `available`, `pending`, `processing`, `optimized`, `rejected`, `unavailable`                                 |

[Pagination](/pagination) has the defaults these parameters fall back to, the page-size cap, and the auto-paginating iterators.

### Get recommendations overview

Returns overview metrics for a provider: total spend, available savings, pending savings, and saved-to-date.

**Python**

```python  
overview = client.recommendations.get_provider_overview("aws")
```

**TypeScript**

```typescript  
const overview = await client.recommendations.getProviderOverview({
    provider_id: "aws",
});
```

**Go**

```go  
overview, err := client.Recommendations.GetProviderOverview(ctx, "aws")
```

### Get recommendation filters

Returns the distinct values available for filtering: environments, accounts, tags, and the virtual tag keys and values your own rules define.

**Python**

```python  
filters = client.recommendations.get_provider_filters("aws")
```

**TypeScript**

```typescript  
const filters = await client.recommendations.getProviderFilters({
    provider_id: "aws",
});
```

**Go**

```go  
filters, err := client.Recommendations.GetProviderFilters(ctx, "aws")
```

## Realized savings

### List realized savings

Returns a paginated, filterable list of realized savings for a provider.

**Python**

```python  
page = client.recommendations.audit.list_by_provider(
    "aws",
    page=1,
    page_size=50,
    preset="6M",
    service=["EC2"],
)
```

**TypeScript**

```typescript  
const page = await client.recommendations.audit.listByProvider({
    provider_id: "aws",
    page_size: 50,
    preset: "6M",
    service: ["EC2"],
});
```

**Go**

```go  
page, err := client.Recommendations.Audit.ListByProvider(ctx, "aws",
    &levelfour.ListByProviderAuditRequest{
        PageSize: levelfour.Int(50),
    },
)
```

### Get realized savings summary

Returns aggregate savings totals for a provider.

**Python**

```python  
summary = client.recommendations.audit.get_provider_summary("aws")
```

**TypeScript**

```typescript  
const summary = await client.recommendations.audit.getProviderSummary({
    provider_id: "aws",
});
```

**Go**

```go  
summary, err := client.Recommendations.Audit.GetProviderSummary(ctx, "aws")
```

## Costs

### Get costs summary

Returns a costs summary for a specific provider.

**Python**

```python  
costs = client.costs.get_provider_summary("aws")
```

**TypeScript**

```typescript  
const costs = await client.costs.getProviderSummary({ provider_id: "aws" });
```

**Go**

```go  
costs, err := client.Costs.GetProviderSummary(ctx, "aws", &levelfour.GetProviderSummaryCostsRequest{})
```

### Get costs filters

Returns distinct services, regions, and accounts available for filtering within a date range.

**Python**

```python  
filters = client.costs.get_provider_filters(
    "aws",
    start="2025-01-01T00:00:00.000Z",
    end="2025-03-31T00:00:00.000Z",
)
```

**TypeScript**

```typescript  
const filters = await client.costs.getProviderFilters({
    provider_id: "aws",
    start: "2025-01-01T00:00:00.000Z",
    end: "2025-03-31T00:00:00.000Z",
});
```

**Go**

```go  
filters, err := client.Costs.GetProviderFilters(ctx, "aws",
    &levelfour.GetProviderFiltersCostsRequest{
        Start: levelfour.String("2025-01-01T00:00:00.000Z"),
        End:   levelfour.String("2025-03-31T00:00:00.000Z"),
    },
)
```

### List costs

Returns a cost breakdown for a provider in multiple formats: `table`, `chart`, `csv`, `raw`.

**Python**

```python  
costs = client.costs.list_by_provider(
    "aws",
    format="table",
    page=1,
    page_size=50,
    sort_by="cost",
    sort_order="desc",
)
```

**TypeScript**

```typescript  
const costs = await client.costs.listByProvider({
    provider_id: "aws",
    format: "table",
    page: 1,
    page_size: 50,
    sort_by: "cost",
    sort_order: "desc",
});
```

**Go**

```go  
costs, err := client.Costs.ListByProvider(ctx, "aws",
    &levelfour.ListByProviderCostsRequest{
        Format:    levelfour.String("table"),
        Page:      levelfour.Int(1),
        PageSize:  levelfour.Int(50),
        SortBy:    levelfour.String("cost"),
        SortOrder: levelfour.ListByProviderCostsRequestSortOrder("desc").Ptr(),
    },
)
```

### Get costs timeline

Returns a costs timeline for a provider over a date range.

**Python**

```python  
timeline = client.costs.get_provider_timeline(
    "aws",
    start="2025-01-01T00:00:00.000Z",
    end="2025-03-31T00:00:00.000Z",
)
```

**TypeScript**

```typescript  
const timeline = await client.costs.getProviderTimeline({
    provider_id: "aws",
    start: "2025-01-01T00:00:00.000Z",
    end: "2025-03-31T00:00:00.000Z",
});
```

**Go**

```go  
timeline, err := client.Costs.GetProviderTimeline(ctx, "aws",
    &levelfour.GetProviderTimelineCostsRequest{
        Start: levelfour.String("2025-01-01T00:00:00.000Z"),
        End:   levelfour.String("2025-03-31T00:00:00.000Z"),
    },
)
```

## Potential savings

### Get potential savings summary

Returns potential savings summary for a provider.

**Python**

```python  
potential = client.recommendations.get_provider_potential_savings_summary("aws")
```

**TypeScript**

```typescript  
const potential = await client.recommendations.getProviderPotentialSavingsSummary({
    provider_id: "aws",
});
```

**Go**

```go  
potential, err := client.Recommendations.GetProviderPotentialSavingsSummary(ctx, "aws")
```

### List potential savings

Returns a paginated potential savings breakdown for a provider.

**Python**

```python  
page = client.recommendations.list_provider_potential_savings(
    "aws",
    page=1,
    page_size=50,
)
```

**TypeScript**

```typescript  
const page = await client.recommendations.listProviderPotentialSavings({
    provider_id: "aws",
    page: 1,
    page_size: 50,
});
```

**Go**

```go  
page, err := client.Recommendations.ListProviderPotentialSavings(ctx, "aws",
    &levelfour.ListProviderPotentialSavingsRecommendationsRequest{
        Page:     levelfour.Int(1),
        PageSize: levelfour.Int(50),
    },
)
```

## Next

* [Recommendations](/resources/recommendations) has the same reads under the `recommendations` namespace, plus the ones that span every provider
* [Costs](/resources/costs) does the same for cost breakdowns, and carries the full grouping and tag filter table
* [Savings](/resources/savings) is realized savings, including the `SavedItem` response shape
* [Filtering and sorting](/guides/filtering-and-sorting) turns these parameters into recipes you can run
* [`/api-reference/providers`](/api-reference/providers) is the generated REST reference for every endpoint here