usage

GET https://geondex.com/api/v1/usage

• Cost: Free
• MCP tool: usage
• Auth: Authorization: Bearer gx_… (see Authentication)
• Try it: Open usage in the playground

Your credit balance, how many credits each tool used this billing cycle, and your most recent calls with status, duration and credits charged. Free. Call it before a large batch to budget, or after a failure to see what happened. Keeps 30 days of calls.

RequestCopy Anchor Link

Query parametersCopy Anchor Link

• limit · integer · optional — How many recent calls to return, newest first. 1–100. Default 20
• tool · string · optional — Only calls to this tool id, e.g. check_visibility. At most 64 characters
• status · "ok" | "error" · optional — Only successful, or only failed, calls

Example requestCopy Anchor Link

curl -s "https://geondex.com/api/v1/usage?limit=2" -H "Authorization: Bearer gx_YOUR_KEY"

ResponseCopy Anchor Link

200 with the envelope every tool returns: a one-line summary, the full data, and credits: { charged, remaining }. On a free call charged is 0 and remaining is null.

Fields of dataCopy Anchor Link

• credits · object
• credits.plan · string
• credits.monthlyAllowance · number
• credits.allowanceRemaining · number
• credits.packRemaining · number
• credits.total · number
• cycle · object
• cycle.since · number — Start of the current allowance cycle (ms)
• cycle.byTool · object[]
• cycle.byTool[].tool · string
• cycle.byTool[].calls · number
• cycle.byTool[].credits · number
• requests · object[]
• requests[].tool · string
• requests[].source · "api" | "mcp" | "playground"
• requests[].status · number — HTTP status the caller got
• requests[].errorCode · string | null
• requests[].credits · number
• requests[].durationMs · number
• requests[].createdAt · number

Example responseCopy Anchor Link

Real-shaped, checked against the output schema by a test. Long lists are shortened.

{
  "summary": "165 credits left; 35 used this cycle across 3 tools.",
  "data": {
    "credits": {
      "plan": "free",
      "monthlyAllowance": 200,
      "allowanceRemaining": 165,
      "packRemaining": 0,
      "total": 165
    },
    "cycle": {
      "since": 1788220800000,
      "byTool": [
        {
          "tool": "keyword_volume",
          "calls": 1,
          "credits": 20
        },
        {
          "tool": "check_visibility",
          "calls": 1,
          "credits": 12
        },
        {
          "tool": "google_rank",
          "calls": 3,
          "credits": 3
        }
      ]
    },
    "requests": [
      {
        "tool": "google_rank",
        "source": "mcp",
        "status": 200,
        "errorCode": null,
        "credits": 1,
        "durationMs": 2140,
        "createdAt": 1790258712000
      },
      {
        "tool": "check_visibility",
        "source": "api",
        "status": 402,
        "errorCode": "credits_exhausted",
        "credits": 0,
        "durationMs": 31,
        "createdAt": 1790258652000
      }
    ]
  },
  "credits": {
    "charged": 0,
    "remaining": 165
  }
}

ErrorsCopy Anchor Link

Every error has the body {"error":{"code":"…","message":"…"}} and is not charged.

Every error.code and what to do about it: Errors & rate limits.