curl --request GET \
--url https://api.refmatter.com/v1/search \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.refmatter.com/v1/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.refmatter.com/v1/search"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"object": "list",
"data": [
{
"object": "item_summary",
"id": "<string>",
"platform": "youtube",
"kind": "video",
"url": "<string>",
"author": {
"object": "account",
"id": "<string>",
"platform": "youtube",
"handle": "<string>",
"name": "<string>",
"url": "<string>"
},
"title": "<string>",
"text": "<string>",
"publishedAt": "<string>",
"publishedText": "<string>",
"durationMs": 4503599627370495,
"stats": {
"views": 4503599627370495,
"likes": 4503599627370495,
"comments": 4503599627370495,
"shares": 4503599627370495,
"saves": 4503599627370495
},
"viewsApproximate": true,
"thumbnails": [
{
"url": "<string>",
"width": 4503599627370495,
"height": 4503599627370495,
"expiresAt": "<string>"
}
],
"live": true,
"ad": {
"archiveId": "<string>",
"pageId": "<string>",
"pageName": "<string>",
"active": true,
"startedAt": "<string>",
"endedAt": "<string>",
"collationId": "<string>",
"collationCount": 4503599627370495,
"displayFormat": "<string>",
"platforms": [
"<string>"
],
"mediaKind": "video",
"spend": "<string>",
"impressions": "<string>",
"reach": 4503599627370495,
"currency": "<string>"
}
}
],
"page": {
"nextCursor": "<string>",
"hasMore": true
},
"total": 4503599627370495,
"totalApproximate": true,
"account": {
"object": "account",
"id": "<string>",
"platform": "youtube",
"handle": "<string>",
"name": "<string>",
"url": "<string>"
},
"observedAt": "<string>",
"cached": true,
"usage": {
"creditsCharged": 4503599627370495,
"lines": [
{
"part": "fetch",
"credits": 4503599627370496
}
]
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}Search a platform
Costs 1 credit for a live page or the first serving of a stored page with at least one row; empty pages, errors and repeats within maxAge are free. Instagram and TikTok publish no anonymous search and answer 422 with a hint. Meta Ad Library answers about advertisers only, one page of up to 15, with no cursor.
curl --request GET \
--url https://api.refmatter.com/v1/search \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.refmatter.com/v1/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.refmatter.com/v1/search"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"object": "list",
"data": [
{
"object": "item_summary",
"id": "<string>",
"platform": "youtube",
"kind": "video",
"url": "<string>",
"author": {
"object": "account",
"id": "<string>",
"platform": "youtube",
"handle": "<string>",
"name": "<string>",
"url": "<string>"
},
"title": "<string>",
"text": "<string>",
"publishedAt": "<string>",
"publishedText": "<string>",
"durationMs": 4503599627370495,
"stats": {
"views": 4503599627370495,
"likes": 4503599627370495,
"comments": 4503599627370495,
"shares": 4503599627370495,
"saves": 4503599627370495
},
"viewsApproximate": true,
"thumbnails": [
{
"url": "<string>",
"width": 4503599627370495,
"height": 4503599627370495,
"expiresAt": "<string>"
}
],
"live": true,
"ad": {
"archiveId": "<string>",
"pageId": "<string>",
"pageName": "<string>",
"active": true,
"startedAt": "<string>",
"endedAt": "<string>",
"collationId": "<string>",
"collationCount": 4503599627370495,
"displayFormat": "<string>",
"platforms": [
"<string>"
],
"mediaKind": "video",
"spend": "<string>",
"impressions": "<string>",
"reach": 4503599627370495,
"currency": "<string>"
}
}
],
"page": {
"nextCursor": "<string>",
"hasMore": true
},
"total": 4503599627370495,
"totalApproximate": true,
"account": {
"object": "account",
"id": "<string>",
"platform": "youtube",
"handle": "<string>",
"name": "<string>",
"url": "<string>"
},
"observedAt": "<string>",
"cached": true,
"usage": {
"creditsCharged": 4503599627370495,
"lines": [
{
"part": "fetch",
"credits": 4503599627370496
}
]
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_input",
"message": "<string>",
"retryable": true,
"requestId": "<string>",
"details": {}
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Which platform to search
youtube, meta_ad_library Search phrase, one to 200 characters
1 - 200Result kind; Meta Ad Library accepts accounts only
items, accounts Item upload date filter; YouTube only
today, week, month, year Item duration filter; YouTube only
short, medium, long Search ordering; YouTube only
relevance, popular ALL, or a two-letter country code; Meta Ad Library only
^(ALL|[A-Za-z]{2})$Opaque cursor from a previous page
How fresh a stored page may be; default 15m
^(0|[1-9][0-9]{0,5}[mhd])$Response
One page of search results
- Option 1
- Option 2
"list"100Show child attributes
Show child attributes
Show child attributes
Show child attributes
0 <= x <= 9007199254740991Show child attributes
Show child attributes
^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$Show child attributes
Show child attributes