# Estimate usage API

URL: https://neattrim.com/docs/tools/estimate_usage

Estimates how much of the account's allowance a planned job will use, from the media duration and options, and whether it fits what is left.

Estimates how much of the account's allowance a planned job will use, from the media duration and options, and whether it fits what is left. Use before long jobs and tell the user the estimate. Works without sign-in (returns the draw only).

Endpoint: `POST /v1/estimate`

MCP name: `estimate_usage` (Available in MCP sets: core, generate, full, local_free)

## What it draws

- Does not draw from the allowance.

## Input

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | string | yes | Operation name, for example subtitle_video, or one of the device tools' AI calls: shorts_moments, shorts_hook, shorts_frames, podcast_notes, ai_text_summary, ai_text_pack, ai_text_hook, ai_text_clips. |
| `duration_seconds` | number | no | Length of the media in seconds. (at least 0) |
| `options` | object | no | The input the job would be given. |

## Output

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `draws` | object | yes |  |
| `fits_allowance` | boolean or null | no |  |
| `display` | string | yes |  |

Endpoint: `POST /v1/estimate`

Who can call it: An API key, or an OAuth token for an app.

## Request body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | string | yes | Operation name, for example subtitle_video, or one of the device tools' AI calls: shorts_moments, shorts_hook, shorts_frames, podcast_notes, ai_text_summary, ai_text_pack, ai_text_hook, ai_text_clips. |
| `duration_seconds` | number | no | Length of the media in seconds. (at least 0) |
| `options` | object | no | The input the job would be given. |

## Examples

Set NEATTRIM_API_KEY to your key, then copy an example. A tool that draws from your allowance reads an uploaded file: upload a sample file as in the quickstart and set VIDEO_FILE_ID (or AUDIO_FILE_ID, IMAGE_FILE_ID, SUBTITLES_FILE_ID) to its file_id. Any other id in an example, such as JOB_ID, is read from a variable of the same name.

### curl

```bash
curl -X POST "https://api.neattrim.com/v1/estimate" \
  -H "Authorization: Bearer $NEATTRIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"compress_video","duration_seconds":6}'
```

### TypeScript

```ts
// @neattrim/sdk is not on npm yet: it arrives with the first client release. Use the curl example today.
import { api, Neattrim, unwrap } from "@neattrim/sdk";

const client = new Neattrim({ apiKey: process.env.NEATTRIM_API_KEY });
const result = unwrap(
  await api.estimateUsage({
    client: client.client,
    body: {
      "tool": "compress_video",
      "duration_seconds": 6
    },
  }),
);
console.log(result);
```

### Python

```python
# neattrim is not on PyPI yet: it arrives with the first client release. Use the curl example today.
import os

from neattrim import Neattrim
from neattrim_generated.api.discovery import estimate_usage
from neattrim_generated.models import EstimateUsageBody

with Neattrim(api_key=os.environ["NEATTRIM_API_KEY"], base_url="https://api.neattrim.com") as client:
    result = estimate_usage.sync(client=client.client, body=EstimateUsageBody.from_dict({"tool": "compress_video", "duration_seconds": 6}))
    print(result)
```

## Response 200

Estimate

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `draws` | object | yes |  |
| `fits_allowance` | boolean or null | no |  |
| `display` | string | yes |  |

## Errors

- `400`: BAD_REQUEST
- `401`: UNAUTHENTICATED or INACTIVE
- `429`: RATE_LIMITED

## Limits

- Largest upload: Free: 200 MB, Plus: 2 GB, Pro: 4 GB
- Jobs running at once: Free: 2, Plus: 3, Pro: 6
- Requests a minute: Free: 60, Plus: 60, Pro: 60
