> **Reading as an AI agent?** This is the Markdown version of https://docs.meshy.ai/api/usage.
>
> - Full docs index: https://docs.meshy.ai/llms.txt
> - Single-fetch full content: https://docs.meshy.ai/llms-full.txt
> - Tool-calling access via MCP server: https://docs.meshy.ai/api/ai

---
# Usage API

The Usage API returns your team's historic API tasks with the credits each one consumed. Filter by time window, endpoint, or status, and page through the results to export in bulk.

> **Note:** **Availability.** The API key must belong to a **Studio** or **Enterprise** team; keys on any other plan, or with no team, receive a `403`.

---

## GET /openapi/v1/usage/tasks -- List Usage Records

Returns one page of the team's API tasks, newest first. Without an explicit time range, the response covers the last 30 days.

### Parameters

  - `page_num` · *integer* · default: `1`

  Page number for pagination.

  - `page_size` · *integer* · default: `10`

  Page size limit. Maximum allowed is `100` items.

  - `sort_by` · *string* · default: `-created_at`

  Field to sort by.

  Available values:
  * `+created_at`: Sort by creation time in ascending order.
  * `-created_at`: Sort by creation time in descending order.

  - `start_time` · *string*

  Start of the `created_at` window, as an RFC 3339 timestamp (e.g. `2026-08-01T00:00:00Z`). Defaults to 30 days before `end_time`. The window may span at most 1 year — for larger exports, page through consecutive windows.

  - `end_time` · *string*

  End of the `created_at` window, as an RFC 3339 timestamp. Defaults to the current time.

  - `endpoints` · *string*

  Comma-separated list of endpoint names to include. Accepts the same values the `endpoint` response field carries — `text-to-3d`, `text-to-3d-preview`, `text-to-3d-refine`, `image-to-3d`, `multi-image-to-3d`, `retexture`, `remesh`, `convert`, `resize`, `uv-unwrap`, `rig`, `animate`, `text-to-motion`, `text-to-image`, `image-to-image`, `print-multi-color`, `print-repair`, `print-analyze`, `print-split` — where `text-to-3d` is an umbrella covering both the preview and refine phases. Omit to include every endpoint.

  - `status` · *string*

  Filter by terminal task status: `SUCCEEDED` or `FAILED`. Omit to include both.

### Returns

Returns a paginated list of [The Usage Record Objects](#the-usage-record-object).

> **Note:** Records cover tasks that have reached a terminal status. Credits are charged when a task is created, so a task still running when you export is not in that window's results yet — re-pull recent windows (or export with a short delay) if your totals must match your credit balance exactly.

> **Note:** Teams with a custom data-retention policy receive records within their configured retention window.

  **cURL**

  ```bash
  curl "https://api.meshy.ai/openapi/v1/usage/tasks?page_size=50&start_time=2026-08-01T00:00:00Z&end_time=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
  ```

  ```javascript
  import axios from 'axios';

  const headers = {Authorization: `Bearer ${YOUR_API_KEY}`};

  try {
    const response = await axios.get(
      'https://api.meshy.ai/openapi/v1/usage/tasks',
      {
        headers,
        params: {
          page_size: 50,
          start_time: '2026-08-01T00:00:00Z',
          end_time: '2026-09-01T00:00:00Z',
        },
      }
    );
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
  ```

  ```python
  import requests

  headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
  }

  response = requests.get(
    "https://api.meshy.ai/openapi/v1/usage/tasks",
    headers=headers,
    params={
      "page_size": 50,
      "start_time": "2026-08-01T00:00:00Z",
      "end_time": "2026-09-01T00:00:00Z",
    },
  )
  response.raise_for_status()
  print(response.json())
  ```

**Response**

```json
[
  {
    "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "endpoint": "image-to-3d",
    "status": "SUCCEEDED",
    "created_at": 1755787000000,
    "finished_at": 1755787045000,
    "consumed_credits": 20,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  },
  {
    "task_id": "018a210d-1c22-7e0f-9d3a-4a5b6c7d8e9f",
    "endpoint": "text-to-3d-refine",
    "status": "FAILED",
    "created_at": 1755786000000,
    "finished_at": 1755786030000,
    "consumed_credits": 0,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  }
]
```

---

## The Usage Record Object

  - `task_id` · *string*

  ID of the task this record bills — the same ID the creating endpoint returned. To fetch the task itself (including its output model or image URLs, re-signed on every read), pass it to the corresponding retrieve endpoint, e.g. `GET /openapi/v1/{endpoint}/{task_id}`.

  - `endpoint` · *string*

  The endpoint the task ran on, e.g. `image-to-3d` or `text-to-3d-refine`. Text to 3D tasks report their phase (`text-to-3d-preview` / `text-to-3d-refine`).

  - `status` · *string*

  Terminal task status: `SUCCEEDED` or `FAILED`.

  - `created_at` · *timestamp*

  Timestamp of task creation, in milliseconds.

  - `finished_at` · *timestamp*

  Timestamp of completion, in milliseconds. `null` if the task carries no completion time.

  - `consumed_credits` · *integer*

  Credits consumed by this task. Returns `0` for `FAILED` tasks (credits are refunded on failure).

  - `api_key_name` · *string*

  Display name of the API key that ran the task. Stays populated for revoked keys, so historic spend remains attributable after key rotation.

  - `api_key_suffix` · *string*

  Last four characters of that API key, for telling keys with the same name apart.

<span id="example-usage-record-object" />

**Example Usage Record Object**

```json
{
  "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "endpoint": "image-to-3d",
  "status": "SUCCEEDED",
  "created_at": 1755787000000,
  "finished_at": 1755787045000,
  "consumed_credits": 20,
  "api_key_name": "production",
  "api_key_suffix": "a1b2"
}
```