curl --request GET \
--url https://api.refmatter.com/v1/items \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.refmatter.com/v1/items', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.refmatter.com/v1/items"
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": {}
}
}List an account's items
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. The account selector names the platform, and each platform reads only its own parameters: a parameter it does not read is refused rather than ignored.
curl --request GET \
--url https://api.refmatter.com/v1/items \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.refmatter.com/v1/items', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.refmatter.com/v1/items"
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
Account selector: a natural key such as youtube:UCX6OQ3DkcsbYNE6H8uQQuVA, :@handle such as instagram:@nike, or an account URL
1 - 2048Collection to list: YouTube videos, shorts or streams; Instagram posts or reels
videos, shorts, streams, posts, reels Ordering: YouTube latest or popular; Meta Ad Library relevance or impressions
latest, popular, relevance, impressions Which ads to list; Meta Ad Library only
active, inactive, all ALL, or a two-letter country code; Meta Ad Library only
^(ALL|[A-Za-z]{2})$Which creative kinds to list; Meta Ad Library only
all, video, image Earliest ad start date, yyyy-mm-dd; Meta Ad Library only
Latest ad start date, yyyy-mm-dd; Meta Ad Library only
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 the account's items
"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