API Reference › Google Ads › get_usage_status

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

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. For annual subscribers it shows the pooled yearly allowance ("X / 1,800 used this year"), the annual reset date, and confirms there is no monthly cap. **Returns:** - Current usage (calls used / limit) — monthly limit or annual pool - Subscription tier (Free, Plus, Pro, Enterprise) and billing period (monthly / annual) - When the quota or annual pool resets - 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.

FieldTypeDescription
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