get_usage_status

Google Ads Read

Get your current usage status with interactive quota widget

Endpoint

POST https://api.adspirer.ai/api/v1/tools/get_usage_status/execute

Headers

Authorization: Bearer sk_live_... — your Adspirer API key (required)
Content-Type: application/json (required)
Idempotency-Key: <uuid> — recommended for write operations to make retries safe

Description

Get your current usage status with interactive quota widget.

This tool shows your tool call usage for the current billing period and provides upgrade options if needed.

**Returns:**
- Current usage (calls used / limit)
- Subscription tier (Free, Plus, Pro, Enterprise)
- Days until quota reset
- Upgrade options with pricing

**Use this tool when:**
- User asks "how many calls do I have left?"
- User asks about their subscription or quota
- User wants to check their usage
- User asks about upgrading their plan

**Widget Display (ChatGPT):**
In ChatGPT, this tool displays an interactive widget with:
- Visual progress bar showing usage
- Upgrade buttons that open Stripe checkout
- Plan comparison with pricing

**Note:** This tool is READ-ONLY and safe to call anytime.

Request body

All tool arguments are wrapped in an arguments object.

Field	Type	Description
No arguments required.

Example request

{
  "arguments": {}
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for get_usage_status)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "get_usage_status"
}

400 — Tool-level error (bad arguments / multi-account selection)

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "get_usage_status"
}

402 — Quota exhausted

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "get_usage_status",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: Google Ads · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai