Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

Open API Credits Balance and Consumption Feedback

Overview

Open API provides two ways to get credits feedback:

  1. Query the account's API credits and monitoring credits balance through /open-api/v1/credits-balance.
  2. 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

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