Competitors

List tracked competitors

social_competitors.competitors.list

Lists the competitors the organization tracks on social media (at most 8), in the order of the screen, paginated by cursor. Each one carries its name, color, tracked profiles per platform (Instagram username, Facebook page, YouTube channel), the public identity read on the last refresh (profile_meta: display name, avatar, bio, website, verified) and when its data was last read (last_fetched_at, last_fetch_error). Metrics are not here: use social_competitors.competitors.get for the latest metrics of one, or social_competitors.snapshots.list for the history. The organization's own brand is not a competitor: see social_competitors.self.get. Requires view access to Competitors. With YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Scope

social_competitors:read

Permission

View the module

MCP tool

social_competitors_competitors_listOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.competitors.list".

Declared cost: up to 201 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/social-competitors" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/social-competitors" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get a competitor with its latest metrics

social_competitors.competitors.get

Returns one competitor (name, tracked profiles, public identity per platform, last refresh) plus latest: for each platform with data, the most recent metrics snapshot (followers, average likes/comments/views of recent posts, engagement rate as a decimal, posts per week, share of reels/shorts, format mix) with its date. Not found (social_competitor_not_found) if the id does not exist in this organization. Requires view access to Competitors. With YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Scope

social_competitors:read

Permission

View the module

MCP tool

social_competitors_competitors_getOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.competitors.get".

Declared cost: up to 4 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/social-competitors/{competitor_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/social-competitors/{competitor_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Start tracking a competitor

social_competitors.competitors.create

Adds a competitor to track: a name and its public profiles (instagram.username, facebook.page_id + page_name, youtube.channel_id + handle; at least one). An organization tracks at most 8 (409 limit_reached, details.resource competitors). Only public data is read: Instagram needs a Business or Creator account and the organization's own Instagram Business account connected; Facebook and Instagram need Meta connected; YouTube works with YouTube connected or the server key. Check identifiers first with social_competitors.lookup.preview, lookup.facebook_pages and lookup.youtube_channel (and lookup.prerequisites for what the organization can track). Right after saving, its data is read from Meta/YouTube in the background (together with the organization's own brand) unless refresh is false; metrics then arrive as snapshots. Returns the new competitor_id, the competitor and warnings: the networks of the competitor this organization cannot read yet (Meta or YouTube not connected, no Instagram Business account of its own), which do not stop the creation. Requires edit access to Competitors.

Scope

social_competitors:write

Permission

Edit in the module

MCP tool

social_competitors_competitors_createOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.competitors.create".

Events it can emit

social_competitors.competitor.createdsocial_competitors.snapshot.created

Declared cost: up to 15 reads and 1 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/social-competitors" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "profiles": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

Rename a competitor or change its profiles

social_competitors.competitors.update

Changes a competitor's name and/or its tracked profiles (updates object). profiles REPLACES the whole set: send every platform that should stay tracked (a platform left out stops being tracked; its past metrics are kept). When profiles is sent, the data is read again from Meta/YouTube right after saving unless refresh is false. Returns the competitor as it is now. Not found (social_competitor_not_found) if the id does not exist in this organization. Requires edit access to Competitors. With YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Scope

social_competitors:write

Permission

Edit in the module

MCP tool

social_competitors_competitors_updateOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.competitors.update".

Events it can emit

social_competitors.competitor.updatedsocial_competitors.snapshot.created

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/social-competitors/{competitor_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

Stop tracking a competitor and delete its history

social_competitors.competitors.delete

Deletes a competitor together with ALL its history: its metric snapshots and its collected posts. The competitor and its most recent history (up to 150 records: one snapshot per platform and day, newest first, then the newest posts) stay 30 days in the trash and owners and admins can restore them with platform.trash.restore; older history does not fit and is deleted for good. Outside the screen it always requires a dry run (which counts the snapshots and posts, and how many fit in the trash) and a confirm_token. Requires edit access to Competitors and, for a credential, deletion enabled.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

social_competitors:write and “Allow deletions” (social_competitors:delete in OAuth)

Permission

Edit in the module

MCP tool

social_competitors_competitors_deleteOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.competitors.delete".

Events it can emit

social_competitors.competitor.deleted

Declared cost: up to 1200 reads and 1000 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/social-competitors/{competitor_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/social-competitors/{competitor_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Read competitors' data from Meta and YouTube now

social_competitors.competitors.refresh

Reads, right now, the public data of one competitor (competitor_id) or of all of them, and always of the organization's own brand, from Meta (Instagram Business Discovery, Facebook Pages) and the YouTube Data API: stores one metrics snapshot per platform, the recent posts (up to 12 per platform) and the public identity, and fires social_competitors.snapshot.created for each snapshot. It takes a few seconds per competitor. A platform that fails does not stop the others: success is false and failures lists competitor, platform and the provider's message (errors carries the same as the screen shows them). Data is already refreshed automatically about once a week (a daily pass reads every competitor not read in the last 6 days, the most overdue first) and when the screen is opened with data older than 6 hours, so call it only when the person asks for fresh data. In demo organizations it does nothing. Not found if competitor_id does not exist. Requires edit access to Competitors.

Scope

social_competitors:write

Permission

Edit in the module

MCP tool

social_competitors_competitors_refreshOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.competitors.refresh".

Events it can emit

social_competitors.snapshot.created

Declared cost: up to 60 reads and 400 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/social-competitors/refresh" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.