Docs · methods

Competitors

Competitors are the companies a project watches. Adding one starts the same background pipeline the app starts: reviews, news, company research, page discovery, social-handle discovery and starter battle cards.

list_competitors · prepare_add_competitor · add_competitor

01

List competitors

list_competitorsread

The competitors tracked in a project, with the social handles and advertiser ids held for each. No googleAdvertiserId means get_google_ads has nothing to join on; no facebookPageId means the same for get_meta_ads.

Parameters3

  • projectIdintegerRequiredProject id from list_projects. Every scoped method needs it.
  • limitintegerOptionalRows to return. Defaults to 20, clamped to 100.
  • cursorstringOptionalnextCursor from the previous page of this same method.

Returns4

  • projectNamestring
  • competitors[]competitorid, name, url, isTracked, companyOneLiner, linkedinHandle, instagramHandle, googleAdvertiserId, facebookPageId.
  • nextCursorstring | nullPass back as cursor to read the next page. Null when done.
  • hasMoreboolean
02

Draft competitors from their websites

prepare_add_competitorwrite

Reads up to 10 competitor websites and returns a draft per url: name, one-liner, LinkedIn handle. Writes nothing. Show the drafts, let the user correct them, then pass the confirmed list to add_competitor. Each url is a scrape plus a model call, so a full list takes about a minute.

Parameters2

  • projectIdintegerRequiredProject id from list_projects. Every scoped method needs it.
  • urlsstring[]RequiredCompetitor websites exactly as pasted, at most 10 per call. Placeholders come back as failed without being read.

Returns4

  • projectNamestring
  • drafts[]draftstatus (prepared or failed), url (normalized to bare domain), name, companyOneLiner, linkedinHandle, failureReason.
  • preparedCountinteger
  • failedCountinteger
03

Add competitors

add_competitorwrite

Adds up to 10 competitors in one call. Pass the whole confirmed list rather than calling once per company; each row is isolated, so one failure does not cost the others. A url already in the project comes back as existing and fills any still-empty fields from what you passed. linkedinHandle and instagramHandle also start tracking that account.

Parameters2

  • projectIdintegerRequiredProject id from list_projects. Every scoped method needs it.
  • competitors[]objectRequiredPer entry: name and url required. Optional: companyOneLiner, headquarters, founded, companySize, revenue, marketShare, tag, context, isAnchor, isTracked, linkedinHandle, instagramHandle, tikTokHandle, youtubeHandle, googleAdvertiserId, googleAdsRegion, facebookPageId, facebookPageUrl.

Returns4

  • projectNamestring
  • results[]resultPer entry: status (added, existing, failed), competitor detail, filledFields, trackedAccounts, researchQueued, battleCardsQueued, failureReason.
  • addedCount / existingCount / failedCountinteger
  • scrapeQueued / researchQueued / battleCardsQueuedbooleanWhether social scrapes, the research pipeline and starter battle cards were actually dispatched.
← ProjectsTracked accounts →