Skip to main content
Issue read-only query tokens for external systems to securely read balance, logs, async tasks, and operational data. The query authorization token is independent of the model token and the profile access token.

​
Create token

Three credential types compared:

​
Read scope (scope_type)

  • user: current user (self only)
  • admin_selected: specified users (allowed_user_ids)
  • admin_all: all users
Current-user tokens ignore user_id and always read self; a token becomes invalid when its issuer is disabled or the admin loses their role; channel / channel_error can only be authorized for the “all users” scope.

​
Permission points

Only resource-level “read” permissions exist in the current version.

​
Calling conventions

  • Auth: pass the query authorization token via the Authorization header.
  • Unified response envelope: success {"success":true,"message":"","data":...}, failure {"success":false,...}; auth failures return HTTP 401/403, business failures return HTTP 200 with success=false.
  • Pagination: page (default 1), size (default 30, max 100), order.
  • Time parameters: default to the last 24h when omitted; time_preset=today|1h|24h|7d; start_time+end_time come as a pair; start_time supports YYYY-MM-DD, YYYY-MM-DD HH:mm:ss, YYYY-MM-DDTHH:mm:ss, RFC3339, and Unix seconds; the five forms are mutually exclusive; logs/tasks span up to 31 days, channel errors 30 days — exceeding limits returns an error.

​
Query endpoint overview

All under /api/query/v1/: balance, balance_alert, model_tokens, logs, logs/{id}, logs/export_jobs(POST), tasks, tasks/{id}, tasks/export_jobs(POST), users, customer_pricing, channels, channel_errors, channel_errors/{id}, channel_errors/export_jobs(POST), export_jobs/{id}, export_jobs/{id}/download, export_jobs/{id}/cancel(POST).

​
Key endpoint fields

  • balance: user_id (required for specified/all), currency=CNY (optional, adds amount columns); data includes today_used_quota, display.enabled always false.
  • model_tokens: returns key_mask (masked, never plaintext), remain_quota/used_quota/monthly_quota/temporary_quota, rate_limit.rpm/tpm, ip_whitelist, model_permissions, balance_alert.
  • logs / logs/{id}: full fields include billing_sku / prompt_tokens / completion_tokens / request_id / platform_request_id / upstream_request_id / platform_price / customer_price / billing / upstream_usage / remain_quota / content(desensitized) / source_ip, etc.
  • tasks / tasks/{id}: platform_task_id, task_id/external_task_id, fail_reason(desensitized), result_urls.
  • customer_pricing: user_id+keyword locates a unique user; returns global_price/customer_price/groups/skus.

​
Export tasks

Three POST creation endpoints; data includes id/resource/status/file_name/row_count/error_msg/expires_at, etc.; a single task supports up to 10,000 rows and a 16 MiB CSV; downloads re-validate permissions and return a CSV stream directly on success.

​
Common errors

Invalid token / query API token does not exist / token disabled / token expired / current source IP not allowed / token not authorized for this permission point / token not allowed to access this user’s data / user_id cannot be empty / time range cannot use two forms at once / query time span exceeds limit / no matching user found / keyword matches multiple users.