Coverage and credit audit exports
Export workspace account Coverage, renewal dates and credit transactions with recorded action references through REST or MCP.
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
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. The report never performs those actions.
Credit transaction audit
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:
{
"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.
- Start with
limit=1000. Allowed values are 1 through 1000. - Process the returned
data. - When
pagination.next_after_idis notnull, pass it asafter_idand reusepagination.as_ofand every original filter. - Stop when
next_after_idisnull. 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, use:
tokportal_export_account_coveragetokportal_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.
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. 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.
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.