Account usage

Page through recorded business calls across your account API keys.

Cost0 credits / call

Account Usage API use cases

Audit recorded calls

An account administrator reviews recorded API calls by key, endpoint and date. The returned usage records help the administrator identify which calls belong to the period being reviewed.

Review actual charges

A finance analyst reviews recorded charges for business API calls before reconciling usage. The analyst checks each returned call status and charged-credit field rather than inferring charges from processing time.

Build an account dashboard

A developer calls the Account Usage endpoint from an internal dashboard using a user API key. The dashboard displays the returned account information without requiring a manual export.

Account Usage API FAQ

What does the Account Usage API return?

List the API calls recorded across the API keys in your Nexscope account. The response includes committed account information for the requested time window. Review the parameter and response tables for the precise meaning of each field. In-flight charges may appear later, and separate account queries do not share a single snapshot.

How many credits does the Account Usage API cost?

This account query is free: 0 credits per call. It reads committed account data without adding a business API call or spending credits. A zero or negative balance does not block the free GET request. Both account queries share a limit of 60 requests per account per 60 seconds.

How do I call the Account Usage API?

Send a GET request to /api/skill-api/v1/account/usage with a GENERAL user API key in the Authorization Bearer header. Supply optional dates and pagination as query parameters rather than a JSON body. The published parameter table describes the UTC time-window rules. Website session tokens and plugin keys cannot authorize this account query.

View plans and credits

Related APIs

Account credits

Read the committed account credit balance and gross ledger consumption.

Account APIs

API overview

Page through recorded business calls across your account API keys.

Endpoint

GET /api/skill-api/v1/account/usage

Authentication

Send a GENERAL user API key in the Authorization bearer header. Website JWTs, plugin keys, and installation tokens cannot call this endpoint. Zero or negative balance does not block this free GET.

Authorization: Bearer YOUR_API_KEY

Run API

Read committed account data without spending credits or adding a business API call. Both queries share a limit of 60 requests per account per 60 seconds.

GET/api/skill-api/v1/account/usage

Run this API

Endpoint

Method	`GET`
Path	`/api/skill-api/v1/account/usage`
Auth	`Bearer API key`
Request body	None. Optional parameters are query fields.

Code example

2026-04-28T20:26:40.000Z → 1777408000000; 2026-05-28T20:26:40.000Z → 1780000000000.

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.nexscope.ai/api/skill-api/v1/account/usage?startTime=1777408000000&endTime=1780000000000&pageNum=1&pageSize=20"

Request parameters

The API uses UTC epoch milliseconds. In Online test, enter UTC date and time; the tester converts those UTC fields to milliseconds without using your browser time zone. With no dates, the preceding 30 days is used. A single bound fills the other with a 30-day span or now. The window is [startTime, endTime), no more than 180 days, and cannot end in the future.

Name	Type	Required	Description
`endTime`	`string`	optional	Optional UTC epoch milliseconds, exclusive. The window must end no later than the request time.
`pageNum`	`integer`	optional	One-based page number. Default: 1 Minimum: 1
`pageSize`	`integer`	optional	Rows per page. Default: 20 Minimum: 1 Maximum: 100
`startTime`	`string`	optional	Optional UTC epoch milliseconds, inclusive. Enter UTC date and time in the tester; the API receives a decimal millisecond string.

Response example

Complete ResponseData envelope. cost is processing time in milliseconds, not charged credits.

{
  "code": 0,
  "msg": null,
  "data": {
    "scope": "API_KEY_CALLS",
    "observedAt": "1780000000000",
    "startTime": "1777408000000",
    "endTime": "1780000000000",
    "grossChargedCredit": "8",
    "calls": {
      "records": [
        {
          "id": "1",
          "createTime": "1779999999000",
          "apiKeyId": "2",
          "path": "/api/skill-api/v1/skills/example/run",
          "method": "POST",
          "callResult": "SUCCESS",
          "chargeStatus": "CHARGED",
          "chargedCredit": "8",
          "requestId": "example-request",
          "correlationRequestId": "example-diagnostic-id",
          "latencyMs": 120
        }
      ],
      "total": "1",
      "size": "20",
      "current": "1",
      "pages": "1"
    }
  },
  "ts": "1780000000000",
  "time": "2026-05-28 20:26:40",
  "cost": "13",
  "traceId": null
}

Response fields

Int64 credits, IDs, page totals, and epoch times are decimal strings; integer status and latency fields remain JSON numbers. Optional fields may be null or absent on error.

Name	Type	Required	Description
`code`	`integer`	optional	Business result code. Only 0 means success, even when HTTP is 200.
`cost`	`string`	optional	Request processing duration in milliseconds, not credits. -1 means non-Web context.
`data`	`object \| null`	optional	Account API Key business-call usage on success; null on an error.
`data.calls`	`object`	optional	Page of business calls, ordered by record ID descending; free account queries are excluded.
`data.calls.current`	`string`	optional	Current one-based page number, decimal string.
`data.calls.pages`	`string`	optional	Calculated page count, decimal string.
`data.calls.records`	`array`	optional	Call records on this page, including failed, rejected, and uncharged calls.
`data.calls.records[]`	`object`	required	Item in data calls records.
`data.calls.records[].apiKeyId`	`string \| null`	optional	Calling API Key ID, decimal string, or null for a rejected call without an identified key.
`data.calls.records[].callResult`	`string`	optional	Business call outcome, including rejected and failed requests. Allowed: SUCCESS, FAILED, REJECTED
`data.calls.records[].chargeStatus`	`string \| null`	optional	Recorded charge state (for example CHARGED, SKIPPED, FAILED, or NOT_CHARGED), or null.
`data.calls.records[].chargedCredit`	`string \| null`	optional	Credits actually charged for this call, decimal string, or null.
`data.calls.records[].correlationRequestId`	`string \| null`	optional	Server-generated ID shared with tool call diagnostics. Use this ID for diagnostic lookup; null for legacy records.
`data.calls.records[].createTime`	`string \| null`	optional	Call creation time in UTC epoch milliseconds, or null.
`data.calls.records[].id`	`string`	optional	API Key call record ID, decimal string.
`data.calls.records[].latencyMs`	`integer \| null`	optional	Call latency in milliseconds, or null.
`data.calls.records[].method`	`string \| null`	optional	Recorded HTTP method, or null.
`data.calls.records[].path`	`string \| null`	optional	Recorded request path, or null.
`data.calls.records[].requestId`	`string \| null`	optional	Original client request ID, or null. This can be reused across calls.
`data.calls.size`	`string`	optional	Requested page size, decimal string.
`data.calls.total`	`string`	optional	Total matching call records, decimal string.
`data.endTime`	`string`	optional	Actual exclusive UTC epoch-millisecond window end.
`data.grossChargedCredit`	`string`	optional	Windowed sum of actual chargedCredit for CHARGED business calls before refunds; decimal string.
`data.observedAt`	`string`	optional	UTC epoch milliseconds when this committed-data read was observed.
`data.scope`	`string`	optional	API Key business-call scope, not the full account ledger or JWT activity. Allowed: API_KEY_CALLS
`data.startTime`	`string`	optional	Actual inclusive UTC epoch-millisecond window start.
`msg`	`string \| null`	optional	Optional business message; may be null or omitted on success.
`time`	`string`	optional	Server-formatted response time (yyyy-MM-dd HH:mm:ss); its zone is not specified by this field.
`traceId`	`string \| null`	optional	Optional error trace ID; may be null or omitted on success.
`ts`	`string`	optional	Server response timestamp, UTC epoch milliseconds as a decimal string.

Responses

HTTP 200	Inspect ResponseData.code: only 0 is a successful business result. A nonzero code may still arrive with HTTP 200.
HTTP 400	Invalid time window or pagination parameters return a parameter error.
HTTP 401 / 403	The key is missing, invalid, or lacks access.
HTTP 429	Shared account-query rate protection; Retry-After: 60 seconds.
HTTP 5xx	Service or dependency error; retry according to the returned status.

grossChargedCredit sums charged business API Key calls before refunds, not all account-ledger consumption. calls includes failed, rejected, and uncharged business calls, but excludes free account queries and JWT activity.

observedAt marks the read time. Only committed results appear; in-flight charges may arrive later. Separate queries do not share a snapshot, and usage pages can shift as calls complete.

What can you do with this API?

Data explained and practical use cases

AI Guide

Question

What usage data can the Account usage API provide, and how might I use it?

AI answer

This API reports API Key business-call records and charged credits for a time window. It includes successful, failed, rejected, and uncharged calls; free account queries are excluded. Its scope is API_KEY_CALLS, not the full account ledger.

Data category	Documented fields	What the values mean
Call outcome	`data.calls.records[].callResult`, `data.calls.records[].chargeStatus`	Whether a call succeeded, failed, or was rejected, and its recorded charge state.
Credits charged	`data.calls.records[].chargedCredit`, `data.grossChargedCredit`	Credits actually charged for an individual call and the window's gross charged total before refunds. Either per-call value may be null.
Called operation	`data.calls.records[].method`, `data.calls.records[].path`, `data.calls.records[].createTime`	Recorded HTTP method, path, and call time when available.
Key and diagnostics	`data.calls.records[].apiKeyId`, `data.calls.records[].correlationRequestId`, `data.calls.records[].requestId`	Calling key ID and identifiers useful for matching a call to diagnostics; some values may be null, and a client request ID can be reused.
Performance	`data.calls.records[].latencyMs`	Recorded call duration in milliseconds, when available.
Paging and window	`data.calls.total`, `data.calls.current`, `data.calls.pages`, `data.startTime`, `data.endTime`	Call count, page position, and the inclusive-start/exclusive-end UTC reporting window.

Audit which API paths an API Key called during the reported window.
- Prompt example: “For the last seven days, list the API paths called by my API Key and the recorded call times. Ask me which key to use if more than one is available, and page through the result before summarizing it.”
Investigate failed or rejected calls alongside their charge states.
- Prompt example: “For my API Key over the last seven days, show failed and rejected calls with callResult, chargeStatus, chargedCredit, path, and time where returned. Do not assume every failure was charged.”
Reconcile charged call records with data.grossChargedCredit before refunds.
- Prompt example: “For my API Key over the last seven days, sum the available chargedCredit values by call and compare them with grossChargedCredit for the returned window. Flag null per-call charges and explain any unresolved difference without inventing refunds.”
Find a call's diagnostic record using correlationRequestId when present.
- Prompt example: “I have a correlationRequestId for a call. Ask me for it, then find the matching API Key call and show its path, time, result, charge state, and diagnostic IDs where available.”
Review latency for calls with recorded latencyMs values.
- Prompt example: “For my API Key over the last seven days, show the calls that have latencyMs, ordered from slowest to fastest. Include path, time, and latency, and distinguish missing latency from zero.”