Pull analytics across all accounts with Hermes Agent

Q: How fresh are the numbers?

`get_analytics_contract` states the freshness rules; most accounts refresh on a schedule and `refresh_account_analytics` can force one when `can_refresh_account_analytics` says so.

Q: Can I get lifetime views per video?

`list_account_video_analytics` and `get_video_analytics` return the per-video counters as collected; series use `mode=cumulative` for running totals or `gained` for deltas.

Q: Is there raw data?

`list_analytics_account_raw_snapshots` and `list_analytics_post_raw_snapshots` expose the underlying snapshots for audits.

From Hermes Agent, one call summarizes every managed account: get_analytics_dashboard (filters platform, country, account, from/to), get_analytics_series for daily or weekly curves of views/likes/comments/shares/followers, list_account_video_analytics per account, get_comment_pulse for what people say, and export_analytics_videos / create_analytics_report for the CSV or branded report. TokPortal collects the numbers because it operates the accounts — no per-account OAuth, no Business-account requirement, no scraping on your side.

Connect TokPortal to Hermes Agent

Hermes Agent is an autonomous agent: Nous Research's open-source agent runtime; MCP servers are declared under mcp_servers in ~/.hermes/config.yaml.

~/.hermes/config.yaml:

mcp_servers:
  tokportal:
    url: "https://app.tokportal.com/api/ext/mcp"
    headers:
      Authorization: "Bearer sk_..."

Or the local stdio form:

mcp_servers:
  tokportal:
    command: "npx"
    args: ["-y", "tokportal-mcp"]
    env:
      TOKPORTAL_API_KEY: "sk_..."

Reload with /reload-mcp. Use tools.include to expose only the read-only tokportal_get_* / tokportal_list_* tools to an unattended agent.

Snippet status: verified against Hermes Agent's documentation (source).

Once connected, sanity-check the setup with a read-only call — "What is my TokPortal credit balance?" should trigger tokportal_get_credit_balance. Every tool runs as your TokPortal account and spends your credits; read-only tools (get_*, list_*, export_*) never do.

How it works

Analytics in TokPortal are workspace-wide and account-scoped at once. Start with get_analytics_contract once — it tells the agent which metrics, granularities and freshness guarantees apply to your workspace — then get_analytics_dashboard for the headline numbers over from/to, filtered by repeatable platform, country and account params. get_analytics_series returns time series with metric (views, likes, comments, shares, followers), granularity (day, week) and mode (cumulative, gained, snapshot) — gained per day is what most dashboards want.

Per account, get_analytics_account (or get_account_analytics) gives the profile-level snapshot and list_account_video_analytics the per-video table (paginated, sort_by/sort_order), which the agent can rank to find winning hooks. Comments: get_comment_pulse for the aggregate mood and list_analytics_account_comments for the text. If a number looks stale, can_refresh_account_analytics says whether a refresh is allowed and refresh_account_analytics triggers it — refreshes are rate-limited by design.

For deliverables, export_analytics_videos returns a CSV filtered by account, platform, country, q, from, to; create_analytics_report returns a structured report and export_analytics_report_html a branded HTML page. From Hermes Agent the useful pattern is a scheduled digest: every morning, dashboard for yesterday, top 5 videos, accounts with zero posts in 7 days (join with list_accounts), any new entries in list_account_bans — posted to Slack or written to a sheet.

Run it from Hermes Agent

Hermes Agent runs autonomously, so the prompt below is written as a goal with an explicit stop before the first write tool. Give it the goal, let it read (get_*, list_*), then confirm before it continues to publish_bundle.

Tool sequence

tokportal_get_analytics_contract — Metrics, granularities and freshness rules for your workspace.
tokportal_get_analytics_dashboard — Totals over from/to with platform/country/account filters.
tokportal_get_analytics_series — metric, granularity, mode, optional account.
tokportal_list_accounts — Enumerate accounts (platform, country, banned=false) to iterate.
tokportal_list_account_video_analytics — Per-video table per account, sortable.
tokportal_get_comment_pulse — Aggregate comment signal across accounts.
tokportal_refresh_account_analytics — Force a refresh when can_refresh_account_analytics allows.
tokportal_export_analytics_videos — CSV for spreadsheets.
tokportal_create_analytics_report — Structured report (or export_analytics_report_html).

Prompt to paste

Use the TokPortal MCP tools. Build my weekly digest: get_analytics_dashboard for the last 7 days,
get_analytics_series (views, day, gained) for the same window, top 5 videos across accounts via
list_account_video_analytics, and any list_account_bans since 7 days ago. Output a short markdown report.

Send the prompt to Hermes; MCP tools are namespaced by server, so look for tokportal_* in the tool list after /reload-mcp.

REST equivalent (same operations, X-API-Key header, base URL https://app.tokportal.com/api/ext)

curl "https://app.tokportal.com/api/ext/analytics?platform=tiktok&country=US&from=2026-08-01&to=2026-08-31" -H "X-API-Key: sk_..."

curl "https://app.tokportal.com/api/ext/analytics/series?metric=views&granularity=day&mode=gained&from=2026-08-01&to=2026-08-31" -H "X-API-Key: sk_..."

curl "https://app.tokportal.com/api/ext/accounts/ACCOUNT_ID/analytics/videos?sort_by=views&sort_order=desc&per_page=10" -H "X-API-Key: sk_..."

curl "https://app.tokportal.com/api/ext/analytics/export/videos?platform=tiktok&from=2026-08-01&to=2026-08-31" -H "X-API-Key: sk_..." -o videos.csv

Key parameters

Parameter	Values	Notes
`from / to`	YYYY-MM-DD	Date window on dashboard, series, exports.
`platform / country / account`	repeatable	Filters on dashboard and exports.
`metric`	views · likes · comments · shares · followers	get_analytics_series.
`granularity / mode`	day · week / cumulative · gained · snapshot	gained+day for daily deltas.
`sort_by / sort_order`	e.g. views · desc	list_account_video_analytics.
`q`	text	Caption search in export_analytics_videos.

Full schemas: OpenAPI reference · openapi.json.

Example configurations

Dashboard call (query)

{"platform":["tiktok","instagram"],"country":["US"],"from":"2026-08-01","to":"2026-08-31"}

Series call (query)

{"metric":"followers","granularity":"day","mode":"gained","account":"ACCOUNT_UUID","from":"2026-08-01","to":"2026-08-31"}

Report request

{"title":"August recap","from":"2026-08-01","to":"2026-08-31","platforms":["tiktok"],"countries":["US","GB"]}

Credits

Analytics reads are free and count only against the 120 requests/minute rate limit. Refreshes are throttled per account (can_refresh_account_analytics). See Credits & Pricing and Analytics API.

Why not the official API

Official insight APIs (TikTok Display/Research, Instagram Graph insights) require each account to be yours, authorized via OAuth, and — on Instagram — a professional account; aggregating 50 accounts means 50 tokens and 50 refresh cycles. TokPortal already operates the accounts and exposes one aggregated, filterable analytics surface.

As of August 2026 the first-party routes look like this. TikTok's Content Posting API (Direct Post) requires each account owner to authorize your app with the video.publish scope, limits every user access token to 6 requests per minute, keeps all posts from unaudited apps in private viewing mode until TikTok audits the app, and enforces an unpublished daily post cap per user (spam_risk_too_many_posts) that integrators commonly report at roughly 15–25 posts per account per day. Meta's Instagram Content Publishing API allows 100 API-published posts per professional account in a 24-hour moving window and only for accounts you own and connect via OAuth. Neither creates accounts, warms them, or reports third-party bans. TokPortal is human-operated infrastructure: accounts created and run by managers in the target country, one X-API-Key for all of them, dated slots (max 3 per day per bundle) instead of per-account tokens.

Sources: TikTok Content Posting API – Direct Post, TikTok Content Posting API – Get started, Instagram Platform – Content Publishing.

Pull analytics across all accounts with Hermes Agent

Connect TokPortal to Hermes Agent

How it works

Run it from Hermes Agent

Key parameters

Example configurations

Credits

Why not the official API

FAQ

How fresh are the numbers?

Can I get lifetime views per video?

How do I build a daily digest?

Is there raw data?

Also works with

Other jobs with Hermes Agent