API Tutorial
How to pull X analytics via API
To get X analytics via API, connect X through Modiva, then call `analytics_unified` — it returns reach, impressions, engagement and follower metrics in one normalised shape you can chart or report on.
Every platform reports metrics differently, so cross-platform reporting usually means a mapping layer per network. Modiva's `analytics_unified` tool returns X metrics in the same schema as every other platform, so one query powers a whole dashboard.
Step by step
Create a Modiva account and MCP key
Sign up free and generate an MCP key (`mk_live_…`) from the dashboard. The same key authenticates both the hosted MCP server (for AI agents) and the REST API (for your backend), so you only manage one credential.
Connect your X account
From the dashboard, click Connect and choose X. Modiva runs the OAuth flow and requests the right scopes for you, then stores the access + refresh tokens in an encrypted vault and keeps them fresh — you never handle X's raw API credentials. The connection gets a stable `connectionId` you reference in every call.
Call analytics_unified for X metrics
Invoke `analytics_unified` with the connection ID, the metrics you want and a period. Modiva fetches them from X, normalises the field names and returns a consistent JSON shape ready to chart.
Roll up every platform into one report
Pass multiple connection IDs to combine X with the rest of your stack in a single response. Over MCP, an agent can pull the numbers and write the weekly report for you, then call `analytics_best_time_to_post` to plan the next one.
Example request
Call the analytics_unified tool through Modiva’s REST API. The same tool is available to AI agents over the MCP server at https://mcp.modiva.ai/v1.
curl -X POST https://api.modiva.ai/v1/tools/invoke \
-H "Authorization: Bearer mk_live_…" \
-H "Content-Type: application/json" \
-d '{
"tool": "analytics_unified",
"connectionId": "conn_…",
"args": { "metrics": ["reach", "engagement"], "period": "last_30_days" }
}'Try it with X
Start freeFAQ
Are X metrics comparable to other platforms?
Yes — Modiva normalises X analytics into a shared schema, so reach and engagement line up across every connected network.
Can an AI agent generate the report?
Yes. Expose `analytics_unified` over MCP and an agent can fetch X numbers and draft the summary on its own.