Concorrentes

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).

Escopo

social_competitors:read

Permissão

Ver o módulo

Tool do MCP

social_competitors_competitors_listNa superfície completa; na compacta, mb_execute_operation com id: "social_competitors.competitors.list".

Custo declarado: até 201 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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).

Escopo

social_competitors:read

Permissão

Ver o módulo

Tool do MCP

social_competitors_competitors_getNa superfície completa; na compacta, mb_execute_operation com id: "social_competitors.competitors.get".

Custo declarado: até 4 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

social_competitors:write

Permissão

Editar no módulo

Tool do MCP

social_competitors_competitors_createNa superfície completa; na compacta, mb_execute_operation com id: "social_competitors.competitors.create".

Eventos que pode emitir

social_competitors.competitor.createdsocial_competitors.snapshot.created

Custo declarado: até 15 leituras e 1 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

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": {}
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar. Na prática esta operação não é simulada (usa outra plataforma): responde 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).

Escopo

social_competitors:write

Permissão

Editar no módulo

Tool do MCP

social_competitors_competitors_updateNa superfície completa; na compacta, mb_execute_operation com id: "social_competitors.competitors.update".

Eventos que pode emitir

social_competitors.competitor.updatedsocial_competitors.snapshot.created

Custo declarado: até 1 leituras e 1 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

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": {}
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar. Na prática esta operação não é simulada (usa outra plataforma): responde 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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

social_competitors:write e «Permitir exclusões» (social_competitors:delete no OAuth)

Permissão

Editar no módulo

Tool do MCP

social_competitors_competitors_deleteNa superfície completa; na compacta, mb_execute_operation com id: "social_competitors.competitors.delete".

Eventos que pode emitir

social_competitors.competitor.deleted

Custo declarado: até 1200 leituras e 1000 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

social_competitors:write

Permissão

Editar no módulo

Tool do MCP

social_competitors_competitors_refreshNa superfície completa; na compacta, mb_execute_operation com id: "social_competitors.competitors.refresh".

Eventos que pode emitir

social_competitors.snapshot.created

Custo declarado: até 60 leituras e 400 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.