Check an Instagram profile or Facebook page before tracking it
social_competitors.lookup.preview
ReadIdempotentSince 2026-11-01
Checks, live against Meta, that an Instagram profile (platform instagram) or a Facebook page (platform facebook) can be tracked, and returns its public card: display_name, handle (the identifier to save: the Instagram username or the page id), avatar_url, followers, verified and extra (e.g. post count). identifier accepts a username, @handle, page id or profile URL. Instead of failing it returns ok=false with error: NOT_FOUND (no such profile), NOT_BUSINESS (a personal Instagram account: Instagram only exposes Business/Creator accounts), NO_OWN_IG (the organization has no Instagram Business account of its own connected, needed to look up others), META_NOT_CONNECTED, EMPTY, or LOOKUP_FAILED with the provider's detail. For YouTube use social_competitors.lookup.youtube_channel. Spends Meta quota. Requires edit access to Competitors.
Scope
social_competitors:read
Permission
Edit in the module
MCP tool
social_competitors_lookup_previewOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.lookup.preview".
Declared cost: up to 3 reads and 0 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.
Parameters
platformenumqueryrequired
instagram or facebook (for YouTube use social_competitors.lookup.youtube_channel).
Values: instagram, facebook
identifierstringqueryrequired
Username, @handle, page id or profile URL (it is normalized: https://instagram.com/nike → nike).
Response
okboolean
true when the profile was found and can be tracked.
errorstring
Why not, when ok is false: NOT_FOUND, NOT_BUSINESS (not an Instagram Business or Creator account), NO_OWN_IG (the organization has no Instagram of its own connected), META_NOT_CONNECTED, EMPTY or LOOKUP_FAILED (then detail).
detailstring
With LOOKUP_FAILED: what the network said.
display_namestring
handlestring
The identifier to send in social_competitors.competitors.create.
avatar_urlstring
followersnumber
verifiedboolean
Facebook only: whether the Page is verified (Instagram does not say).
post_countnumber
Instagram: the profile's posts.
extrastring
The line the screen shows under the profile (in Spanish); use post_count instead.
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.
GET/v1/social-competitors/lookup/facebook-pages
Search Facebook pages by name
social_competitors.lookup.facebook_pages
ReadIdempotentSince 2026-11-01
Searches public Facebook pages by name through Meta (up to 8 results: id, name, verified, link), to find the page_id of a competitor's page. If the person already has the page URL or username, social_competitors.lookup.preview with platform facebook resolves it directly. Errors: 409 integration_not_connected (details.platform meta: connect Meta in Settings → Integrations), 409 external_rejected (Meta rejected the search: its code in details.provider_code and its text in provider_message), 429 external_rate_limited or 503 external_unavailable (Meta is limiting or not answering: retry after retry_after), 409 integration_reconnect_required (the Meta connection expired). Spends Meta quota. Requires edit access to Competitors.
Scope
social_competitors:read
Permission
Edit in the module
MCP tool
social_competitors_lookup_facebook_pagesOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.lookup.facebook_pages".
Declared cost: up to 2 reads and 0 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.
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.
GET/v1/social-competitors/lookup/prerequisites
Which platforms the organization can track
social_competitors.lookup.prerequisites
ReadIdempotentSince 2026-11-01
Says which competitor platforms this organization can track right now, without calling any platform: meta (Meta connected, its own or inherited from its agency: needed for Instagram and Facebook), own_instagram (its own Instagram Business account connected: needed to read other Instagram profiles) and youtube (YouTube connected or the server's public key available). Use it before adding a competitor to tell the person what to connect in Settings → Integrations. Requires view access to Competitors.
Scope
social_competitors:read
Permission
View the module
MCP tool
social_competitors_lookup_prerequisitesOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.lookup.prerequisites".
Declared cost: up to 6 reads and 0 writes per call (they count against the daily quota).
