curl --request GET \
--url https://api.refmatter.com/v1/items/lookup \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.refmatter.com/v1/items/lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.refmatter.com/v1/items/lookup"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"object": "item",
"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>",
"durationMs": 4503599627370495,
"stats": {
"views": 4503599627370495,
"likes": 4503599627370495,
"comments": 4503599627370495,
"shares": 4503599627370495,
"saves": 4503599627370495
},
"thumbnails": [
{
"url": "<string>",
"width": 4503599627370495,
"height": 4503599627370495,
"expiresAt": "<string>"
}
],
"transcript": {
"language": "<string>",
"source": "captions",
"segments": [
{
"startMs": 4503599627370495,
"endMs": 4503599627370495,
"text": "<string>"
}
],
"text": "<string>"
},
"unavailableFields": [
"author"
],
"ad": {
"archiveId": "<string>",
"deeplinkId": "<string>",
"pageId": "<string>",
"pageName": "<string>",
"byline": "<string>",
"active": true,
"startedAt": "<string>",
"endedAt": "<string>",
"platforms": [
"<string>"
],
"displayFormat": "<string>",
"collationId": "<string>",
"collationCount": 4503599627370495,
"spend": "<string>",
"impressions": "<string>",
"reach": 4503599627370495,
"currency": "<string>",
"creatives": [
{
"index": 4503599627370495,
"kind": "image",
"title": "<string>",
"body": "<string>",
"caption": "<string>",
"linkUrl": "<string>",
"linkDescription": "<string>",
"callToAction": "<string>",
"callToActionType": "<string>",
"thumbnail": {
"url": "<string>",
"width": 4503599627370495,
"height": 4503599627370495,
"expiresAt": "<string>"
}
}
]
},
"tiktok": {
"authorSecUid": "<string>",
"authorVerified": true,
"reposts": 4503599627370495,
"hashtags": [
"<string>"
],
"music": {
"id": "<string>",
"title": "<string>",
"authorName": "<string>",
"original": true
},
"isAd": true,
"aiGenerated": true,
"width": 4503599627370495,
"height": 4503599627370495,
"originalLanguage": "<string>",
"captionLanguages": [
"<string>"
]
},
"instagram": {
"mediaId": "<string>",
"productType": "<string>",
"carouselCount": 4503599627370495,
"likesHidden": true,
"hasAudio": true,
"captionEdited": true,
"authorVerified": true,
"width": 4503599627370495,
"height": 4503599627370495,
"accessibilityCaption": "<string>"
},
"youtube": {
"availability": "public",
"liveState": "not_live",
"captionTracks": [
{
"language": "<string>",
"kind": "manual"
}
],
"categories": [
"<string>"
],
"tags": [
"<string>"
],
"channelFollowerCount": 4503599627370495,
"commentCountApproximate": true
},
"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": {}
}
}Look up one public item
Costs 1 credit for a live fetch, and for the first time a workspace is served a stored observation. A repeat within maxAge is free and reports cached true while the store serves the observation the workspace already paid for; once another workspace or an import records changed counts, the next repeat costs 1 credit. Every error charges nothing: the answer is always an item or a typed failure, never a job to poll. Responses carry Refmatter-Credits-Charged, and a success also carries Server-Timing.
curl --request GET \
--url https://api.refmatter.com/v1/items/lookup \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.refmatter.com/v1/items/lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.refmatter.com/v1/items/lookup"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"object": "item",
"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>",
"durationMs": 4503599627370495,
"stats": {
"views": 4503599627370495,
"likes": 4503599627370495,
"comments": 4503599627370495,
"shares": 4503599627370495,
"saves": 4503599627370495
},
"thumbnails": [
{
"url": "<string>",
"width": 4503599627370495,
"height": 4503599627370495,
"expiresAt": "<string>"
}
],
"transcript": {
"language": "<string>",
"source": "captions",
"segments": [
{
"startMs": 4503599627370495,
"endMs": 4503599627370495,
"text": "<string>"
}
],
"text": "<string>"
},
"unavailableFields": [
"author"
],
"ad": {
"archiveId": "<string>",
"deeplinkId": "<string>",
"pageId": "<string>",
"pageName": "<string>",
"byline": "<string>",
"active": true,
"startedAt": "<string>",
"endedAt": "<string>",
"platforms": [
"<string>"
],
"displayFormat": "<string>",
"collationId": "<string>",
"collationCount": 4503599627370495,
"spend": "<string>",
"impressions": "<string>",
"reach": 4503599627370495,
"currency": "<string>",
"creatives": [
{
"index": 4503599627370495,
"kind": "image",
"title": "<string>",
"body": "<string>",
"caption": "<string>",
"linkUrl": "<string>",
"linkDescription": "<string>",
"callToAction": "<string>",
"callToActionType": "<string>",
"thumbnail": {
"url": "<string>",
"width": 4503599627370495,
"height": 4503599627370495,
"expiresAt": "<string>"
}
}
]
},
"tiktok": {
"authorSecUid": "<string>",
"authorVerified": true,
"reposts": 4503599627370495,
"hashtags": [
"<string>"
],
"music": {
"id": "<string>",
"title": "<string>",
"authorName": "<string>",
"original": true
},
"isAd": true,
"aiGenerated": true,
"width": 4503599627370495,
"height": 4503599627370495,
"originalLanguage": "<string>",
"captionLanguages": [
"<string>"
]
},
"instagram": {
"mediaId": "<string>",
"productType": "<string>",
"carouselCount": 4503599627370495,
"likesHidden": true,
"hasAudio": true,
"captionEdited": true,
"authorVerified": true,
"width": 4503599627370495,
"height": 4503599627370495,
"accessibilityCaption": "<string>"
},
"youtube": {
"availability": "public",
"liveState": "not_live",
"captionTracks": [
{
"language": "<string>",
"kind": "manual"
}
],
"categories": [
"<string>"
],
"tags": [
"<string>"
],
"channelFollowerCount": 4503599627370495,
"commentCountApproximate": true
},
"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
Absolute http or https URL of one post, video, short or ad
1 - 2048Also return a transcript built from captions
transcript How fresh a stored observation must be to be served: 0 or a whole number of minutes, hours or days up to 365d, such as 30m, 1h or 7d. Default 1h; 0 always fetches live
^(0|[1-9][0-9]{0,5}[mhd])$Response
The item as it was observed
"item"^(youtube|tiktok|instagram|meta_ad_library):[A-Za-z0-9._-]{1,128}$youtube, tiktok, instagram, meta_ad_library video, short, image, carousel, ad 1 - 2048Show child attributes
Show child attributes
100010000^\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)$0 <= x <= 9007199254740991Show child attributes
Show child attributes
64Show child attributes
Show child attributes
Show child attributes
Show child attributes
12author, title, text, publishedAt, durationMs, stats.views, stats.likes, stats.comments, stats.shares, stats.saves, thumbnails, transcript Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show 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