Source: https://developers.tokportal.com/list-and-read-comments/ Markdown: https://developers.tokportal.com/list-and-read-comments.md # List & Read ## List ``` GET /api/ext/comments ``` Returns a paginated list of your tasks, newest first. | Param | Type | Description | | ------------------ | ------------- | -------------------------------------------------------------------------------- | | `status` | string | Comma-separated list of statuses to filter by — e.g. `status=pending,submitted`. | | `saved_account_id` | string (UUID) | Restrict to a specific account. | | `page` | integer | 1-indexed page (default 1). | | `per_page` | integer | 1–100 (default 25). | ```bash curl -X GET "https://app.tokportal.com/api/ext/comments?status=manually_confirmed&per_page=50" \ -H "X-API-Key: sk_xxx" ``` **Response:** ```json { "data": [ { "id": "0d8b5a3e-92c4-4111-9a7d-3e2f1a2b3c4d", "status": "manually_confirmed", "platform": "tiktok", "saved_account_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c", "target_type": "video", "target_video_url": "https://www.tiktok.com/@someone/video/7000000000000000000", "target_comment_url": null, "target_comment_id": null, "target_author_handle": "someone", "comment_text": "Brilliant idea", "cm_payout_amount": 0.24, "submitted_at": "2026-04-27T17:21:34Z", "verified_at": null, "manually_confirmed_at": "2026-04-28T13:56:11Z", "client_dispute_deadline_at": "2026-05-01T13:56:11Z", "finalized_at": null, "correction_required": null, "deadline_at": "2026-04-30T17:21:00Z", "execution_blocked": false, "execution_blocked_at": null, "execution_block_reason": null, "created_at": "2026-04-27T17:18:37Z", "updated_at": "2026-04-28T13:56:11Z" } ], "pagination": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1 } } ``` ## Read one ``` GET /api/ext/comments/{id} ``` Same task shape as in the list, wrapped under `data`. ```bash curl -X GET https://app.tokportal.com/api/ext/comments/0d8b5a3e-92c4-4111-9a7d-3e2f1a2b3c4d \ -H "X-API-Key: sk_xxx" ``` Returns `404 COMMENT_TASK_NOT_FOUND` if the ID is unknown, `403 COMMENT_TASK_NOT_OWNED` if it belongs to another user. ## Cancel a pending task ``` DELETE /api/ext/comments/{id} ``` Atomically refunds the task's exact stored purchase cost and flips it to `cancelled`. New tasks normally refund 1 credit, while historical tasks can have a different stored cost. Only `credits_refunded` in the response is authoritative. Cancellation works only while the task is still `pending` (the manager hasn't posted yet), including when TokPortal Coverage currently pauses execution. ```bash curl -X DELETE https://app.tokportal.com/api/ext/comments/0d8b5a3e-92c4-4111-9a7d-3e2f1a2b3c4d \ -H "X-API-Key: sk_xxx" \ -H "Idempotency-Key: comments-cancel-018f4a1d" ``` **Response:** ```json { "data": { "id": "0d8b5a3e-92c4-4111-9a7d-3e2f1a2b3c4d", "status": "cancelled", "credits_refunded": 1 } } ``` If the manager has already moved the task past `pending`, you'll get a `409 COMMENT_INVALID_STATUS` with the current status in `details.current_status`. From `submitted` onwards there is no cancellation — the workflow is already in flight. ## Field reference | Field | Type | Description | | ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string (UUID) | Task ID. | | `status` | string | See the [lifecycle](https://developers.tokportal.com/comments-overview#lifecycle) for the full list. | | `platform` | string | `tiktok` / `instagram`. Snapshot of the account's platform at create time. | | `saved_account_id` | string (UUID) | The account posting the comment. | | `target_type` | string | `video` (comment under a video) or `comment` (reply to a specific comment). | | `target_video_url` | string | Canonicalized URL of the target video (`tiktok.com/@x/video/...`, `instagram.com/reel/...`). For a comment target, this is the video the comment lives under. | | `target_comment_url` | string \| null | Deep-link to the target comment. Set only when `target_type` is `comment`. | | `target_comment_id` | string \| null | The id of the comment to reply to. Set only when `target_type` is `comment`. | | `target_author_handle` | string \| null | Parsed from the URL when available (TikTok `/@handle/video/...`). | | `comment_text` | string | Exact text the manager posts. | | `cm_payout_amount` | number | Manager's USD payout. `0.15` while pending; final value once `verified_auto` / `finalized`. | | `submitted_at` | string \| null | When the manager declared they posted. | | `verified_at` | string \| null | When auto-verification matched the comment. | | `manually_confirmed_at` | string \| null | When the manager manually confirmed (couldn't auto-verify). | | `client_dispute_deadline_at` | string \| null | UTC cutoff for you to dispute a `manually_confirmed` task. Auto-finalizes after that. | | `finalized_at` | string \| null | When the payout was locked. | | `correction_required` | string \| null | Human-readable instructions when the task is `pending_corrections` (your dispute reason or a verifier-detected mismatch). | | `deadline_at` | string | Hard 72h deadline. Past this, `pending` tasks auto-cancel + refund. | | `execution_blocked` | boolean | `true` when inactive TokPortal Coverage currently prevents manager execution without changing the durable workflow status. | | `execution_blocked_at` | string \| null | When TokPortal withheld this task from manager execution. | | `execution_block_reason` | string \| null | Stable account or Coverage reason. Fetch `GET /api/ext/accounts/{saved_account_id}/managed-subscription` for recovery details. | | `created_at` / `updated_at` | string | ISO 8601 timestamps. | When `execution_blocked` is true, keep the task in client history but do not interpret it as manager-late work. Reactivate Coverage only from a fresh quote. If the task remains `pending`, you may instead cancel it with the exact-retry header shown above.