Scan a competitor's content

A marketing tool can build a competitor scan from Refmatter’s search, account, list, and import endpoints. This recipe starts with a Meta Ad Library advertiser, checks the advertiser’s public profiles, collects candidates from each platform, ranks them in your own code, and imports the items worth keeping.

1. Find the advertiser

Search the Meta Ad Library by the name the user supplies. The SDK sets type=accounts; the REST request states it explicitly.

curl -G https://api.refmatter.com/v1/search \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  --data-urlencode "platform=meta_ad_library" \
  --data-urlencode "type=accounts" \
  --data-urlencode "q=Dot & Key"

const advertisers = await refmatter.search.accounts({
  platform: 'meta_ad_library',
  q: 'Dot & Key',
});

const advertiser = advertisers.data[0];
if (!advertiser) throw new Error('No advertiser found');

Pick a result row and keep its id. The row carries name, meta_ad_library.category, stats.followers (the Meta page like count), and meta_ad_library.instagramHandle.

{
  "object": "account",
  "id": "meta_ad_library:100200300400500",
  "platform": "meta_ad_library",
  "handle": "dotandkey",
  "name": "Dot & Key",
  "url": "https://www.facebook.com/ads/library/?view_all_page_id=100200300400500",
  "description": null,
  "avatar": [],
  "verified": true,
  "stats": { "followers": 412903 },
  "meta_ad_library": {
    "category": "Beauty, cosmetic & personal care",
    "likes": 412903,
    "instagramHandle": "dotandkey.skincare",
    "instagramFollowers": 688400,
    "instagramVerified": true,
    "pageDeleted": false
  }
}

Look up Instagram, TikTok, and YouTube separately. Use meta_ad_library.instagramHandle for Instagram. TikTok and YouTube need a handle the user already has; the Ad Library result does not carry those handles.

curl -G https://api.refmatter.com/v1/accounts/lookup \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  --data-urlencode "platform=instagram" \
  --data-urlencode "handle=dotandkey.skincare"

curl -G https://api.refmatter.com/v1/accounts/lookup \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  --data-urlencode "platform=tiktok" \
  --data-urlencode "handle=dotandkey"

curl -G https://api.refmatter.com/v1/accounts/lookup \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  --data-urlencode "platform=youtube" \
  --data-urlencode "handle=NASA"

const instagram = await refmatter.accounts.lookup({
  platform: 'instagram',
  handle: advertiser.meta_ad_library!.instagramHandle!,
});
const tiktok = await refmatter.accounts.lookup({
  platform: 'tiktok',
  handle: 'dotandkey',
});
const youtube = await refmatter.accounts.lookup({
  platform: 'youtube',
  handle: '@NASA',
});

Instagram and TikTok publish no anonymous account search. accounts.lookup works by a known handle, URL, or id, so the handle must come from the advertiser row or the user; never guess one. The account response includes the platform’s public profile data, such as name, description, url, avatar, verified, and stats. Platform-specific blocks add the fields that platform publishes: for example, Instagram has instagram.private, while TikTok has tiktok.likes and tiktok.private. See Look up an account for the full response fields and platform differences.

3. Collect candidates

List each account with the platform-specific selector. The advertiser id is the selector for the Meta page. For the Meta page, request active ads. Each row can represent a near-identical variant group; ad.collationCount tells you how many variants are in that group. If total is large, split the request into ad start-date windows with since and until.

TypeScript

const ads = await refmatter.items.list({
  account: advertiser.id,
  status: 'active',
});

For Instagram, make two list calls: reels for engagement counts and posts for captions. Instagram returns 12 rows per page.

TypeScript

const reels = await refmatter.items.list({
  account: 'instagram:@dotandkey.skincare',
  type: 'reels',
});
const posts = await refmatter.items.list({
  account: 'instagram:@dotandkey.skincare',
  type: 'posts',
});

For TikTok, the list is the 10 newest videos and has no cursor. For YouTube, ask for popular items and follow its cursor.

TypeScript

const tiktok = await refmatter.items.list({ account: 'tiktok:@dotandkey' });
const youtube = await refmatter.items.list({
  account: 'youtube:@NASA',
  sort: 'popular',
});

const moreYoutube =
  youtube.page.nextCursor === null
    ? null
    : await refmatter.items.list({ cursor: youtube.page.nextCursor });

The same cursor rule applies to Instagram and YouTube: pass page.nextCursor as cursor alone. The cursor already carries the platform, account, and filters, so do not repeat account, type, sort, or other filters on the next call. TikTok and the Ad Library have no cursor. See List an account’s items for the complete paging rules and response fields.

4. Rank candidates in your code

Refmatter returns candidates; it does not rank them for you. Build a score that fits the product’s goal from the fields available on each platform:

Use stats.views, stats.likes, and stats.comments where the platform provides them. Instagram reels provide those engagement fields; YouTube provides views; TikTok provides a view count but its item rows do not provide likes or comments.
Use ad.startedAt, ad.endedAt, and ad.collationCount to compare active periods and the number of near-identical ad variants. Ad Library rows do not provide public engagement counts.
Use publishedAt and publishedText where present. Several values are null: list rows normally have publishedAt: null for YouTube, Instagram does not provide publishedText, and TikTok does not provide publishedText.
Keep the platform’s null values as unknown rather than treating them as zero. The item list guide describes what each platform provides and omits.

For example, a score can combine views and likes for Instagram reels, views and publishedText for YouTube, views and recency for TikTok, and start date plus ad.collationCount for Meta ads. The weights and the treatment of missing values belong in your application.

5. Import the chosen items

Import each selected row’s url. Use imports.create when you want to manage the import job yourself, or use the SDK’s importUrl convenience wrapper to create the import and wait for its reference.

curl -X POST https://api.refmatter.com/v1/imports \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  -H "Idempotency-Key: competitor-scan-dot-key-001" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=21X5lGlDOfg","mediaProfile":"full"}'

const { importJob, reference } = await refmatter.importUrl(selected.url, {
  waitFor: 'reference',
});
if (reference === null) {
  throw new Error(`${importJob.outcomeCode}: ${importJob.outcomeMessage}`);
}

const savedReference = await refmatter.references.get(reference.id);
if (savedReference.primaryMediaId !== null) {
  const media = await refmatter.media.access(savedReference.primaryMediaId);
  console.log(media.downloadUrl);
}

The REST import returns an id and, once the reference is readable, a referenceId. Read that reference with GET /v1/references/{referenceId}. In the SDK, importUrl returns { importJob, reference }; reference is null when the import failed before a reference existed. Use primaryMediaId with GET /v1/media/{mediaId}/download-url or refmatter.media.access(mediaId) for a media download URL. See Import a URL, References, and Media access.

{
  "mediaId": "01a0a04b-0000-4000-8000-000000000001",
  "downloadUrl": "https://r2.cloudflarestorage.com/refmatter/01a0a04b-0000-4000-8000-000000000001?X-Amz-Signature=example",
  "expiresAt": "2026-09-14T14:27:00.000Z",
  "contentType": "video/mp4",
  "filename": "21X5lGlDOfg.mp4"
}

6. Budget the scan

Plan roughly one credit for each live page that has at least one row, or for the first stored serving of a page with a row. Repeats within maxAge are free, empty pages are free, and every error is free. That means the scan can usually reuse a fresh advertiser search, account lookup, or item page without charging again; the two Instagram list types are separate pages. See Search, Look up an account, and List an account’s items for the endpoint-specific credit rules. Every response includes Refmatter-Credits-Remaining, the workspace balance after the response. A live request at a zero balance returns 402 insufficient_credits. If the service returns 429 rate_limited, use the Retry-After header before trying again. Errors do not charge credits.

Not in this endpoint

This recipe does not provide private account data, anonymous Instagram or TikTok account search, public engagement counts that a platform does not publish, or a server-side ranking. It also does not import every row automatically: choose the candidates in your own code and import only the URLs your workflow needs.

Get started

Item data

Lists, search and comments

Reference library

SDK and agents

Policies

Scan a competitor's content

1. Find the advertiser

3. Collect candidates

4. Rank candidates in your code

5. Import the chosen items

6. Budget the scan

Not in this endpoint

Next steps

​1. Find the advertiser

​2. Confirm the social accounts

​3. Collect candidates

​4. Rank candidates in your code

​5. Import the chosen items

​6. Budget the scan

​Not in this endpoint

​Next steps

1. Find the advertiser

2. Confirm the social accounts

3. Collect candidates

4. Rank candidates in your code

5. Import the chosen items

6. Budget the scan

Not in this endpoint

Next steps