Open API Credits Balance and Consumption Feedback

Overview

Open API provides two ways to get credits feedback:

Query the account's API credits and monitoring credits balance through /open-api/v1/credits-balance.
Read the remaining credits after the current request and the credits consumed by the current request directly from the standard response body of business APIs, such as search APIs, detail APIs, and monitoring APIs.

These two approaches can be used for frontend balance display, API call logs, balance monitoring, and low-balance alerts.

Credits Balance Query API

API Information

Request Method: POST
Endpoint: /open-api/v1/credits-balance
Description: Query the API credits and monitoring credits balance details for the account associated with the current API key.
Pricing: Free to query. This endpoint does not consume API credits or monitoring credits.
Rate Limit: Approximately 1000 requests per minute globally and 60 requests per minute per API key. If the limit is exceeded, the API returns 444.

Request Headers:

Content-Type: application/json
Accept: application/json

Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	External API request key of the user	"your_api_key_here"

Request Example

curl -X POST "https://www.pipispy.com/open-api/v1/credits-balance" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here"
  }'

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "total_api_credits": 10000,
    "remaining_api_credits": 8500,
    "purchased_api_credits": 10000,
    "used_api_credits": 1500,
    "total_monitor_credits": 5000,
    "remaining_monitor_credits": 4200,
    "purchased_monitor_credits": 5000,
    "used_monitor_credits": 800
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "success": true,
  "fail": false
}

data Field Description

Field	Type	Description
total_api_credits	Long	Total API credits. If credits are deducted and later refunded, this value may be greater than `purchased_api_credits`
remaining_api_credits	Long	Remaining API credits, used for data query APIs such as search and detail APIs
purchased_api_credits	Long	Total purchased API credits
used_api_credits	Long	Total used API credits
total_monitor_credits	Long	Total ad/store monitoring credits. If credits are deducted and later refunded, this value may be greater than `purchased_monitor_credits`
remaining_monitor_credits	Long	Remaining ad/store monitoring credits
purchased_monitor_credits	Long	Total purchased ad/store monitoring credits
used_monitor_credits	Long	Total used ad/store monitoring credits

Credits Feedback in Business APIs

In addition to the credits balance query API, business APIs such as search APIs, detail APIs, and monitoring APIs return the following fields in the standard response body:

Field	Type	Description
remaining_credits	Long	Current remaining available credits. Data query APIs return remaining API credits; monitoring APIs return remaining monitoring credits
consumed_credits	Long	Credits actually consumed by the current request. Returns 0 for free access, failed requests, or requests with no credits deducted

Business API Response Example

{
  "code": 200,
  "message": "success",
  "data": {},
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Applicable APIs

API Type	Entry Point	Credits Meaning
Search APIs	`/open-api/v1/data`	Returns remaining API credits and credits consumed by the current search request
Detail APIs	`/open-api/v1/data`	Returns remaining API credits and credits consumed by the current detail query
Monitoring APIs	`/open-api/v1/monitor/data`	Returns remaining monitoring credits and credits consumed by the current monitoring operation
Monitoring Task APIs	`/open-api/v1/ad-monitor-task/*`	Returns remaining monitoring credits and credits consumed by the current monitoring task operation

Error Codes

Error Code	Description
200	Success
400	Invalid request parameters. The API key is empty or the request body format is invalid
401	Authentication failed. The API key is invalid or expired
442	Insufficient credits
444	Request too frequently. The rate limit has been triggered
500	Internal server error. Please try again later

Recommendations

Call /open-api/v1/credits-balance when you need to display complete balance details.
After each business API call, read remaining_credits and consumed_credits directly to record the credits consumed by the request.
When remaining_credits falls below your internal threshold, trigger alerts through email, Feishu, DingTalk, Slack, or other channels.
If the account has not enabled a certain credit capability, the corresponding balance fields may return null.
Balance monitoring tasks are recommended to call the API at minute-level intervals or lower frequency to avoid triggering rate limits.