SetToRun

Early access. These guides cover the current product build. Access and connected-channel availability depend on your organization's setup. Public Instagram messaging access is not available yet.

Connect to the API and MCP server

Operator and Agency workspaces can connect external tools to their recorded activity. The first API and MCP tools are read-only: message summaries, top incoming DM contacts and campaign completion counts.

They do not send messages, activate Plays, change contacts or expose a general database query tool. Their reporting numbers follow the same definitions as the activity assistant.

Manage your connection

An owner or admin opens Settings → Developer access in the correct workspace. Create a credential with the analytics:read scope and an expiry date. Copy the secret when it is first shown and store it in your integration's secret manager.

The secret is not shown again. If it is lost, revoke that credential and create another. Do not put it into a URL, public website, browser bundle or support message.

Credentials are bound to one workspace and member. Current plan access and membership are checked on each request. Revocation, expiry, a plan downgrade or loss of the required membership blocks later requests. A trial follows its current effective plan; trial expiry does not leave paid API access behind.

What you can read

  • Message summary: recorded incoming DMs and provider-acknowledged outgoing messages/replies, with attempts and unknown outcomes kept separate.
  • Top incoming contacts: contacts ranked by recorded incoming DM count. Missing names remain unnamed.
  • Campaign completions: email or keyword completions and distinct participating contacts for the selected campaign and period. These are not unique historical email-address counts or consent records.

Every result includes its period and scope. Check coverage before interpreting missing data or comparing reports. Use channel and campaign filters to narrow a report. Your client must handle the documented range and rate limits rather than repeatedly retrying rejected requests.

Make an API request

Send a JSON POST to https://hooks.settorun.com/api/v1/analytics. Supply your credential in the Authorization header. Do not supply a workspace ID: the credential determines which workspace can be read.

curl --request POST 'https://hooks.settorun.com/api/v1/analytics' \
  --header "Authorization: Bearer $SETTORUN_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"operation":"message_summary"}'

SETTORUN_API_TOKEN is your locally stored secret, not a literal token to copy from this guide. This example uses the default last 30 days. The response shows the actual period.

Supported operations are message_summary, top_incoming_contacts and campaign_completions. Optional filters are since, until, timezone, channelId, playId, limit and offset. Supply since and until together as timestamps. The start is inclusive, the end exclusive, and the maximum range is 366 days. playId selects a campaign for campaign completions; incoming DMs cannot be attributed to a Play. Ranked contacts use a maximum page size of 50.

A rejected credential returns 401, an invalid request 400, a rate limit 429 and an unavailable report 503. Do not treat an unavailable report as a zero count. Correct invalid requests and expired/revoked credentials before trying again.

Limits allow 60 authorization admissions per minute per credential and 300 per workspace. MCP discovery and tool reads both count, so one tool call can use two admissions. These deterministic reporting reads do not use AI credits.

API versus MCP

Use the API when your own integration needs structured reporting results. Use MCP when a compatible assistant or tool needs to discover and call those same reporting operations.

The initial MCP connection requires a client that supports a preconfigured HTTP Authorization: Bearer header. It does not provide OAuth sign-in or a one-click ChatGPT connector. A normal API credential cannot authorize an AI request or spend the workspace's AI credits.

The remote MCP endpoint is https://hooks.settorun.com/mcp. Configure it as an HTTP MCP server with Authorization: Bearer <your credential> stored securely by your client. The server negotiates the MCP protocol and lists only the reporting tools currently available to that credential. Tool names match the three API operations above.

Use the endpoint and setup examples shown in Developer access. Verify the selected workspace before connecting. Revoke the credential when an integration is no longer needed.