> For the complete documentation index, see [llms.txt](https://helpcenter.paperguide.ai/llms.txt).
> Use it to discover all available pages before exploring further.

# Check Usage

Paperguide Usage API for checking current API usage, remaining quota, and plan limits in your integration.



<PlaygroundComponent />

<AuthParams schemes={["ApiKeyAuth"]}>
<AuthType scheme="ApiKeyAuth">
<ParamField header="x-api-key" param-type="string" required="true">
API Key for authentication. Provide your API key in the header.
</ParamField>
</AuthType>
</AuthParams>

<Request tabs="curl,python,javascript,go,ruby">

```bash
curl -X GET "https://api.paperguide.ai/v1/usage" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"
```

```python
import requests
import json

url = "https://api.paperguide.ai/v1/usage"
headers = {
  "Content-Type": "application/json",
  "x-api-key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())
```

```javascript
const response = await fetch("https://api.paperguide.ai/v1/usage", {
  method: "GET",
  headers: {
  "Content-Type": "application/json",
  "x-api-key": "YOUR_API_KEY"
}
});

const data = await response.json();
console.log(data);
```

```go
package main

import (
    "fmt"
    "net/http"
)

func main() {

    req, err := http.NewRequest("GET", "https://api.paperguide.ai/v1/usage", nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-api-key", "YOUR_API_KEY")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}
```

```ruby
require 'net/http'
require 'json'

uri = URI('https://api.paperguide.ai/v1/usage')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
request['x-api-key'] = 'YOUR_API_KEY'

response = http.request(request)
puts response.body
```

</Request>

### Responses

<div data-component="ResponsesCollection"><Expandable title="200 - Usage details returned successfully." default-open="true">

<ResponseField name="monthly_used" field-type="integer" required="true">
Number of requests or units used in the current billing period.
</ResponseField>

<ResponseField name="monthly_quota" field-type="integer" required="true">
Monthly quota for the account. A value of `-1` means there is no monthly quota limit.
</ResponseField>

<ResponseField name="rate_limit_per_minute" field-type="integer" required="true">
Allowed request rate per minute.
</ResponseField>

</Expandable>

<Expandable title="400 - Bad Request. The request was invalid or missing required parameters." default-open="false">

<ResponseField name="error" field-type="string" required="true">
Short machine-readable error code.
</ResponseField>

<ResponseField name="message" field-type="string" required="true">
Human-readable error message.
</ResponseField>

</Expandable>

<Expandable title="401 - Unauthorized. The API key is missing or invalid." default-open="false">

<ResponseField name="error" field-type="string" required="true">
Short machine-readable error code.
</ResponseField>

<ResponseField name="message" field-type="string" required="true">
Human-readable error message.
</ResponseField>

</Expandable>

<Expandable title="429 - Too Many Requests. The rate limit has been exceeded." default-open="false">

<ResponseField name="error" field-type="string" required="true">
Short machine-readable error code.
</ResponseField>

<ResponseField name="message" field-type="string" required="true">
Human-readable error message.
</ResponseField>

</Expandable>

<Expandable title="500 - Internal Server Error. An unexpected error occurred." default-open="false">

<ResponseField name="error" field-type="string" required="true">
Short machine-readable error code.
</ResponseField>

<ResponseField name="message" field-type="string" required="true">
Human-readable error message.
</ResponseField>

</Expandable>

</div>

<Response tabs={["200","400","401","429","500"]} dropdown="true">

```json
{
  "monthly_used": 124,
  "monthly_quota": 1000,
  "rate_limit_per_minute": 30
}
```

```json
{
  "error": "invalid_request",
  "message": "The request was invalid or missing required parameters."
}
```

```json
{
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
```

```json
{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Please try again later."
}
```

```json
{
  "error": "internal_error",
  "message": "An unexpected server error occurred."
}
```

</Response>

## Endpoint overview

Check your current API usage for the billing period, including your quota and per-minute rate.

<Callout kind="info">

Add your API key to the `x-api-key` header on every request. Create API keys in **Settings > API Keys** in the Paperguide dashboard.

```bash
x-api-key: pg_api_example_9xmk7q2r
```

</Callout>

## Method and path

```bash
GET /v1/usage
```

Send requests to the Paperguide API base URL:

```bash
https://api.paperguide.ai/v1
```

## Request example

<Request>
```bash
curl -X GET "https://api.paperguide.ai/v1/usage" \
  -H "x-api-key: pg_api_example_9xmk7q2r"
```
</Request>

## Response example

<Response>
```json
{
  "monthly_used": 4,
  "monthly_quota": 10,
  "rate_limit_per_minute": 5
}
```
</Response>

## Response fields

<ResponseField name="monthly_used" field-type="integer" required="true">
Number of API calls your account has used in the current billing period.
</ResponseField>

<ResponseField name="monthly_quota" field-type="integer" required="true">
Monthly API call quota for your plan.
</ResponseField>

<ResponseField name="rate_limit_per_minute" field-type="integer" required="true">
Maximum number of requests your plan allows per minute.
</ResponseField>

## What `monthly_quota = -1` means

A `monthly_quota` value of `-1` means your plan does not have a monthly quota limit.

For Enterprise, usage is billed based on how many API calls you make instead of a fixed monthly quota. Contact us for Enterprise access. Enterprise billing is `$0.01` per API call.

## How usage relates to rate limits and quotas

Your plan sets two limits: a monthly quota and a per-minute request limit. If you go over either limit, the API returns `429 Too Many Requests`.

For Enterprise, usage reflects pay-per-call billing instead of a fixed monthly quota. Enterprise also supports up to 50 papers per request.

## Error responses

The API returns JSON errors when a request fails.

| Status | Meaning |
| ------ | ------- |
| `400`  | Invalid request parameters |
| `401`  | Missing or invalid API key |
| `429`  | Rate limit or monthly quota exceeded |
| `500`  | Internal server error |