> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gregapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query authorization

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:

| Token type | Purpose | Common paths |
| - | - | - |
| Model token | Call models | `/v1/*`, `/kling/*`, `/vidu/*` |
| Profile access token | Query own profile & balance | `/api/user/*` |
| Query authorization token | Read-only query of account/logs/tasks/operations | `/api/query/v1/*` |

## 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

| Permission ID | current user | specified users | all users |
| - | - | - | - |
| `account_balance` | ✓ | ✓ | ✓ |
| `balance_alert` | ✓ | - | - |
| `model_token` | ✓ | - | ✓ |
| `log` | ✓ | ✓ | ✓ |
| `task` | ✓ | ✓ | ✓ |
| `user` | - | ✓ | ✓ |
| `customer_pricing` | - | ✓ | ✓ |
| `channel` | - | - | ✓ |
| `channel_error` | - | - | ✓ |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.