# Retrieve Usage

> GET /usage — what your account has used this period, next to its plan limits.

`GET /usage`

Returns your account's meters next to the limits of its plans, in three groups: **transactional** (email sending), **marketing** (contacts and segments) and **team** (shared across the account). Use it to warn before a limit is reached, or to show usage inside your own tools. No prices or amounts are included.

> **Note:** Works with any API key that has read access. Takes no parameters.

**Node.js**

```js
const res = await fetch('https://www.senddart.com/api/usage', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);
```

**Ruby**

```ruby
require 'net/http'
require 'uri'

uri = URI('https://www.senddart.com/api/usage')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer mb_xxxxxxxxx'
res = http.request(req)
puts res.body
```

**PHP**

```php
<?php
$ch = curl_init('https://www.senddart.com/api/usage');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer mb_xxxxxxxxx',
        'User-Agent: my-app/1.0',
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```

**Python**

```python
import requests

res = requests.get(
    "https://www.senddart.com/api/usage",
    headers={"Authorization": "Bearer mb_xxxxxxxxx"},
)
print(res.json())
```

**Go**

```go
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://www.senddart.com/api/usage", nil)
    req.Header.Set("Authorization", "Bearer mb_xxxxxxxxx")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    fmt.Println(string(out))
}
```

**Rust**

```rust
use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let res = Client::new()
        .get("https://www.senddart.com/api/usage")
        .header("Authorization", "Bearer mb_xxxxxxxxx")
        .header("User-Agent", "my-app/1.0")
        .send()
        .await?;
    println!("{}", res.text().await?);
    Ok(())
}
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.senddart.com/api/usage"))
    .header("Authorization", "Bearer mb_xxxxxxxxx")
    .header("User-Agent", "my-app/1.0")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

**.NET**

```csharp
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://www.senddart.com/api/usage");
request.Headers.Add("Authorization", "Bearer mb_xxxxxxxxx");
request.Headers.Add("User-Agent", "my-app/1.0");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

**cURL**

```bash
curl -X GET 'https://www.senddart.com/api/usage' \
  -H 'Authorization: Bearer mb_xxxxxxxxx'
```

### Response

```json
{
  "object": "usage",
  "transactional": {
    "plan": { "id": "pro", "name": "Pro" },
    "monthly": { "used": 51234, "limit": 50000, "received": 1210 },
    "daily": { "used": 900, "limit": null, "received": 30 },
    "webhook_endpoints": { "used": 2, "limit": 5 }
  },
  "marketing": {
    "plan": { "id": "mkt_free", "name": "Marketing Free" },
    "contacts": { "used": 812, "limit": 1000 },
    "segments": { "used": 1, "limit": 3 },
    "broadcasts": "unlimited"
  },
  "team": {
    "ai_credits": { "used": 12, "limit": 100 },
    "automation_runs": { "used": 10340, "limit": 10000 },
    "domains": { "used": 4, "limit": 110 },
    "inboxes": { "used": 5, "limit": 3 },
    "retention_days": 30
  }
}
```

**Fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `transactional.plan` | object | No | The sending plan: `id` and display `name`. |
| `transactional.monthly` | object | No | Emails sent this billing month (`used`) against the monthly `limit`, plus emails `received` by your domains. |
| `transactional.daily` | object | No | The same for today (UTC). |
| `transactional.webhook_endpoints` | object | null | No | Webhook endpoints in use against the plan's allowance. `null` on older plans that have no such limit. |
| `marketing.plan` | object | No | The marketing plan: `id` and `name`. |
| `marketing.contacts` | object | No | Stored contacts against the plan's allowance. |
| `marketing.segments` | object | No | Segments against the plan's allowance. |
| `marketing.broadcasts` | string | No | Always `"unlimited"`: campaigns are not counted. |
| `team.ai_credits` | object | No | AI credits used this period. |
| `team.automation_runs` | object | No | Automation runs started this period. |
| `team.domains` | object | No | Domains on the account. |
| `team.inboxes` | object | No | Inboxes on the account against the number included. |
| `team.retention_days` | number | No | How many days of email history the account keeps. |

Every meter is `{ used, limit }`. A `limit` of `null` means there is no limit. `used` can be higher than `limit` (as `monthly` and `automation_runs` are above) when usage went past an allowance, for example on pay-as-you-go or during a grace period.

A missing or invalid key returns `401`. A key without read access returns `401 restricted_api_key`; see [Errors](https://www.senddart.com/docs/api/errors).
