Source: https://developers.tokportal.com/audit-reports/
Markdown: https://developers.tokportal.com/audit-reports.md

# Coverage and credit audit exports

Use these read-only bulk reports to audit your workspace without requesting each account, bundle or transaction separately. Both endpoints return up to **1,000 records per call**, use your existing API key's read permission, and cost **0 credits**. They do not renew Coverage, debit credits, reveal credentials or contact social platforms. Normal API authentication, billing restrictions and read rate limits still apply.

Base URL: `https://app.tokportal.com/api/ext`

## Account Coverage report

```bash
curl 'https://app.tokportal.com/api/ext/reports/account-coverage?limit=1000' \
  -H "X-API-Key: $TOKPORTAL_API_KEY"
```

The report includes all your saved accounts by default, including hidden/removed accounts. Set `include_hidden=false` to exclude those. Banned accounts are identified separately. It contains no passwords, verification codes or manager details.

| Field                                           | Meaning                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_id`, `username`, `platform`, `country` | Account identifiers.                                                                                                                                                                                                                                                                                                                          |
| `profile_url`, `dashboard_url`                  | Public profile and TokPortal account links.                                                                                                                                                                                                                                                                                                   |
| `coverage_fee_required`                         | Whether this account is subject to recurring Coverage fees under the existing account policy. `false` identifies exempt/legacy accounts. It does not make video slots or other paid actions free.                                                                                                                                             |
| `coverage_on_now`                               | Whether the account's canonical Coverage/account-state gate currently permits managed work. A ban, pending ban appeal, hidden account or another block can make this false even when a paid period exists. This is not API connection readiness.                                                                                              |
| `action_block_reason`                           | The exact block reason, or `null` when work is permitted.                                                                                                                                                                                                                                                                                     |
| `coverage_status`                               | `exempt` when no subscription exists and no fee is required; `not_enrolled` when a fee is required but no subscription exists; otherwise the effective recorded subscription status. An expired active/included period is `lapsed`. `not_enrolled` alone does not mean grandfathered or blocked. Check the fee requirement and access fields. |
| `recorded_status`                               | Stored subscription status, or `null`. It can temporarily differ from the effective state at a period boundary.                                                                                                                                                                                                                               |
| `auto_renew`                                    | Renewal is enabled for a fee-bearing, eligible `included` or `active` subscription. This is false for cancelled renewals, exempt accounts and unavailable account states. It does not guarantee a future charge or sufficient credits.                                                                                                        |
| `next_renewal_at`                               | Next automatic renewal due date when enabled, otherwise `null`.                                                                                                                                                                                                                                                                               |
| `current_period_end`                            | Current subscription period boundary, or `null` without a subscription.                                                                                                                                                                                                                                                                       |
| `paid_or_included_through`                      | End of the last recorded paid/included period. This historical date alone never overrides an unpaid period or another account block.                                                                                                                                                                                                          |
| `period_rate_credits`                           | This account's stored 30-day Coverage rate, or `null`. No price is recalculated by the report.                                                                                                                                                                                                                                                |
| `cancelled_at`, `unpaid_periods`                | Renewal cancellation timestamp and recorded unpaid periods already due.                                                                                                                                                                                                                                                                       |
| `hidden`, `banned`, `credentials_revealed`      | Separate account-state flags. `banned` includes recorded or detected bans.                                                                                                                                                                                                                                                                    |

**Renewal off is different from Coverage off.** A cancelled renewal can retain access through the already-paid period when no earlier period is unpaid. Exempt accounts have no recurring Coverage renewal to pay. Use the fields together rather than treating every `cancelled` row as an inactive account.

For an explicit Coverage reactivation quote or a pause/reactivation action, continue to use the existing [Coverage endpoints](https://developers.tokportal.com/saved-accounts#tokportal-coverage). The report never performs those actions.

## Credit transaction audit

```bash
curl 'https://app.tokportal.com/api/ext/reports/credit-transactions?limit=1000&date_from=2026-11-01&date_to=2026-11-16' \
  -H "X-API-Key: $TOKPORTAL_API_KEY"
```

Omit both dates for all recorded history. Dates are inclusive UTC creation dates. A reversed range or an impossible calendar date returns HTTP 400.

| Field                                                                         | Meaning                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transaction_id`, `created_at`                                                | Stable ledger ID and timestamp.                                                                                                                                                                                                                             |
| `credits_movement`                                                            | Original signed credit movement: positive adds credits, negative spends credits. Unlike the remaining amount, it does not shrink as a grant is consumed. A legacy row with no original amount returns `null`, not an invented zero or reconstructed amount. |
| `remaining_grant_credits`                                                     | Remaining amount of a positive grant at the time of the read. `null` for debits or when the original grant amount is unknown.                                                                                                                               |
| `recorded_balance_after`                                                      | Historical balance as recorded, or `null`. It is not reconstructed.                                                                                                                                                                                         |
| `type`, `source`, `description`                                               | Original ledger classification and description.                                                                                                                                                                                                             |
| `expires_at`, `expired_at`                                                    | Expiration information.                                                                                                                                                                                                                                     |
| `action.kind`, `action.quantity`, `action.initial_video_slots`                | Recorded action kind and purchase quantities, when present. Quantity is not the credit price.                                                                                                                                                               |
| `action.related_bundle_id`, `action.bundle_url`                               | Recorded bundle reference and link.                                                                                                                                                                                                                         |
| `action.related_subscription_id`                                              | Recorded plan subscription reference, when present.                                                                                                                                                                                                         |
| `action.saved_account_id`, `action.video_listing_id`, `action.video_position` | Explicit recorded account/video references, when present. Account-edit charges can also recover their account from an owned request with the exact same credit transaction ID.                                                                              |
| `action.link_status`                                                          | `recorded_reference` when a resource reference exists. `not_recorded` when neither the historical ledger nor an exact owned account-edit backlink retains a resource reference.                                                                             |

**References are evidence of a recorded association, not delivery confirmation.** A bundle may have since been cancelled, removed or replaced. Historical actions do not all have a video-level reference. Missing references remain explicit; TokPortal never invents a match from a similar amount or timestamp. An exact account-edit backlink is labelled `action.kind=account_edit_request`. Ambiguous backlinks to different accounts remain unlinked. The report excludes raw operational metadata, API secrets and account credentials. Cash invoices and credit consumption are separate records.

## Pagination and consistency

Both responses have this envelope:

```json
{
  "data": [],
  "pagination": {
    "limit": 1000,
    "as_of": "2026-11-16T12:00:00.000Z",
    "next_after_id": null
  }
}
```

The Coverage report also returns `evaluated_at` for the live evaluation time of that page.

1. Start with `limit=1000`. Allowed values are 1 through 1000.
2. Process the returned `data`.
3. When `pagination.next_after_id` is not `null`, pass it as `after_id` and reuse `pagination.as_of` and every original filter.
4. Stop when `next_after_id` is `null`. An exactly full final page can be followed by one empty final page.

Rows are ordered by immutable ID, **not chronological order**. Sort the complete exported ledger by `created_at` if needed. ID cursors avoid offset shifts during concurrent inserts or deletes. `as_of` excludes rows created after the initial request; it is not a frozen database snapshot. Existing account state, Coverage, grant remainders or records can change between pages. Keep page evaluation times when you need to audit those changes. Check HTTP errors and respect `Retry-After` on HTTP 429. Never interpret a failed or interrupted export as complete.

## MCP and AI agents

On the [remote MCP](https://developers.tokportal.com/mcp/remote), use:

- `tokportal_export_account_coverage`
- `tokportal_export_credit_transactions`

Both tools are marked read-only and expose the same pagination parameters and response fields as REST. Reconnect or refresh your MCP tool catalogue after an update if the new names do not appear. Existing installed local MCP/SDK package versions do not gain new methods until those packages are updated; REST and remote MCP use the deployed server.

You can give your agent this instruction:

> Export every page of account Coverage and credit transactions for my current TokPortal workspace, using the two read-only export tools. Keep the first as\_of and all filters for each report. Follow next\_after\_id until null. Write separate CSV files. Preserve all IDs and exact credit movements, distinguish renewal-off-but-paid accounts from expired Coverage, and explicitly retain not\_recorded action links. Do not reactivate, pause, reveal, buy, refund or publish anything. Report a failed page rather than presenting a partial file as complete.

## Download both reports as CSV

This Python 3 script uses only the standard library. Save it as `export_tokportal_audit.py`, set `TOKPORTAL_API_KEY` in your environment, then run `python3 export_tokportal_audit.py`. It streams pages to temporary files and publishes each final CSV only after its complete export succeeds.

```python


BASE = "https://app.tokportal.com/api/ext"
KEY = os.environ["TOKPORTAL_API_KEY"]

def get_page(path, params):
    url = BASE + path + "?" + urllib.parse.urlencode(params)
    for attempt in range(5):
        try:
            req = urllib.request.Request(url, headers={"X-API-Key": KEY})
            with urllib.request.urlopen(req, timeout=60) as response:
                return json.load(response)
        except urllib.error.HTTPError as exc:
            if exc.code != 429 or attempt == 4:
                raise
            time.sleep(max(1, int(exc.headers.get("Retry-After", "60"))))
    raise RuntimeError("Export page was not received")

def flatten(row):
    out = {}
    for key, value in row.items():
        if isinstance(value, dict):
            out.update({key + "." + k: v for k, v in value.items()})
        else:
            out[key] = value
    out = {k: json.dumps(v, ensure_ascii=False) if isinstance(v, (dict, list)) else v for k, v in out.items()}
    # Preserve numeric negative movements. Escape text formula prefixes in CSV.
    return {k: "'" + v if isinstance(v, str) and v.startswith(("=", "+", "-", "@", "\t", "\r")) else v
            for k, v in out.items()}

def export(path, filename, filters=None):
    params = {"limit": 1000, **(filters or {})}
    temporary = filename + ".partial"
    count = 0
    writer = None
    with open(temporary, "w", newline="", encoding="utf-8-sig") as handle:
        while True:
            page = get_page(path, params)
            for record in page["data"]:
                row = flatten(record)
                if writer is None:
                    writer = csv.DictWriter(handle, fieldnames=list(row))
                    writer.writeheader()
                writer.writerow(row)
                count += 1
            paging = page["pagination"]
            if paging["next_after_id"] is None:
                break
            params.update(as_of=paging["as_of"], after_id=paging["next_after_id"])
    os.replace(temporary, filename)
    print(filename, count, "records")

export("/reports/account-coverage", "account_coverage.csv")
export("/reports/credit-transactions", "credit_transactions.csv")
```

To restrict the ledger to a date range, pass `{"date_from": "2026-11-01", "date_to": "2026-11-16"}` as the third argument of its `export` call. This does not alter the account Coverage report.

## Detailed balances, references and bulk review

Choose **View all** under Plan & credits, or open [Credit transactions](https://app.tokportal.com/dashboard/credits/transactions). This workspace-wide screen searches the entire history on the server, shows result counts and movement totals, supports filters and sorting, and exports every matching page to CSV. Expand a transaction for full IDs, copy controls, links and the recorded purchase breakdown. Export progress and cancellation are available; a failed export never downloads an apparently complete file.

The REST report and `tokportal_export_credit_transactions` return the same detailed rows:

| Added field                                                          | Meaning                                                                                                                                                                         |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `balance_before`                                                     | Recorded balance after minus the original signed movement. `null` if either input is missing. Never computed from remaining grant credits or by summing other history.          |
| `balance_after`                                                      | Alias of the historical `recorded_balance_after`.                                                                                                                               |
| `balance_basis`                                                      | `recorded_after_minus_movement` or `unavailable`.                                                                                                                               |
| `action.order_id`, `action.order_url`                                | Exact recorded order reference or exact owned account-edit backlink, when available.                                                                                            |
| `action.current_order_ids`, `action.current_order_urls`              | Current non-cancelled bundle orders. These are current context, not proof of the order at purchase. Multiple orders remain an array.                                            |
| `action.account_id`, `action.account_username`, `action.account_url` | Current owned account details. The original `saved_account_id` remains the stored reference.                                                                                    |
| `action.account_relation`                                            | `recorded`, `exact_edit_backlink`, `current_bundle` or `not_recorded`. Current relationships may have changed since purchase.                                                   |
| `action.bundle_title`                                                | Current title of the owned bundle, if it still exists.                                                                                                                          |
| `action.video_listing_ids`, `action.video_reference_status`          | Exact video IDs recorded for this purchase. New additional-slot purchases record inserted IDs atomically; older gaps remain `not_recorded`. No matching by timestamp or amount. |
| `action.videos`                                                      | Current platform post IDs/URLs and positions for recorded video IDs still owned by this workspace. A purchased slot can exist before a platform post exists.                    |
| `action.post_id`                                                     | Platform post ID when one recorded video is found; multiple videos remain in `videos`.                                                                                          |
| `action.price_components`                                            | Recorded initial-purchase breakdown in credits, when present. Current prices are never substituted.                                                                             |

### Search and pagination options

| Parameter                                                 | Meaning                                                                                                                                     |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `q`                                                       | Literal case-insensitive search, at most 200 characters, across description, kind, recorded IDs, current bundle title and account username. |
| `direction`                                               | `all` (default), `debit` or `credit`.                                                                                                       |
| `kind`                                                    | Exact activity kind, for example `bundle_video_slots`, `bundle_credit_payment` or `tokportal_coverage_renewal`.                             |
| `account_id`, `bundle_id`, `order_id`, `video_listing_id` | Exact UUID filter. Account/order filtering may include the explicitly labelled current context.                                             |
| `sort_by`                                                 | `id` (default), `created_at` or `credits_movement`.                                                                                         |
| `sort_order`                                              | `asc` (default) or `desc`. ID is the stable tie-breaker for equal values.                                                                   |
| `offset`                                                  | Zero-based row offset, up to 1,000,000.                                                                                                     |

`pagination.total` and `summary.credits_in`, `summary.credits_out` (positive magnitude), and `summary.unknown_movements` cover the entire filtered set before pagination. These are credit movements, not cash invoices or delivery confirmation.

```bash
curl 'https://app.tokportal.com/api/ext/reports/credit-transactions?limit=100&direction=debit&sort_by=created_at&sort_order=desc' \
  -H "X-API-Key: $TOKPORTAL_API_KEY"
```

For date or movement sorting, continue with `pagination.next_offset`, the same `as_of`, sort and filters until `next_offset` is `null`. The existing `next_after_id` cursor remains supported with default ascending ID order. Do not combine `after_id` with another sorting mode or a nonzero offset. The CSV script above uses the default ID cursor and still exports the complete ledger. Refresh the remote MCP tool catalogue to discover the added parameters.
