Competidores

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

Alcance

social_competitors:read

Permiso

Ver el módulo

Tool del MCP

social_competitors_competitors_listEn la superficie completa; en la compacta, mb_execute_operation con id: "social_competitors.competitors.list".

Costo declarado: hasta 201 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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).

Alcance

social_competitors:read

Permiso

Ver el módulo

Tool del MCP

social_competitors_competitors_getEn la superficie completa; en la compacta, mb_execute_operation con id: "social_competitors.competitors.get".

Costo declarado: hasta 4 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

social_competitors:write

Permiso

Editar en el módulo

Tool del MCP

social_competitors_competitors_createEn la superficie completa; en la compacta, mb_execute_operation con id: "social_competitors.competitors.create".

Eventos que puede emitir

social_competitors.competitor.createdsocial_competitors.snapshot.created

Costo declarado: hasta 15 lecturas y 1 escrituras por llamada (cuentan en el cupo diario). Toca una plataforma externa (meta): cuenta en el cupo de operaciones externas.

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar. En la práctica esta operación no se simula (toca otra 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).

Alcance

social_competitors:write

Permiso

Editar en el módulo

Tool del MCP

social_competitors_competitors_updateEn la superficie completa; en la compacta, mb_execute_operation con id: "social_competitors.competitors.update".

Eventos que puede emitir

social_competitors.competitor.updatedsocial_competitors.snapshot.created

Costo declarado: hasta 1 lecturas y 1 escrituras por llamada (cuentan en el cupo diario). Toca una plataforma externa (meta): cuenta en el cupo de operaciones externas.

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar. En la práctica esta operación no se simula (toca otra 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.

Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.

Alcance

social_competitors:write y «Permitir eliminar» (social_competitors:delete en OAuth)

Permiso

Editar en el módulo

Tool del MCP

social_competitors_competitors_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "social_competitors.competitors.delete".

Eventos que puede emitir

social_competitors.competitor.deleted

Costo declarado: hasta 1200 lecturas y 1000 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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.

Alcance

social_competitors:write

Permiso

Editar en el módulo

Tool del MCP

social_competitors_competitors_refreshEn la superficie completa; en la compacta, mb_execute_operation con id: "social_competitors.competitors.refresh".

Eventos que puede emitir

social_competitors.snapshot.created

Costo declarado: hasta 60 lecturas y 400 escrituras por llamada (cuentan en el cupo diario). Toca una plataforma externa (meta): cuenta en el cupo de operaciones externas.

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar. En la práctica esta operación no se simula (toca otra plataforma): responde 409 sandbox_external_unavailable.