Deep-dive lookup

Place lookup (beta)

Beta: TikTok places only. Instagram places are not available yet. A place is the location tag a creator chose on a post, usually where the video was filmed. The numbers are the posts creators tagged at the place, TikTok's own tag count, and how that count changed between lookups. These endpoints describe what's posted at a place, never where one person has been.

See what's being posted at one TikTok place right now, and how its tag count has changed.

At a glance

What it does: Reads the posts tagged at one venue or area fresh from TikTok, adds the ones Virlo already has, and sums up their views, creators, hashtags and dates.
You send: The place: a Virlo place id, TikTok's own place id, or its name.
You get back: A job_id right away. Check it every 5 to 10 seconds until it says completed.
Cost: $0.50 per lookup started. A name that matches several places returns them free, and so does the same place again within 6 hours when you ask for as many posts or fewer.
How long: Usually under a minute. A lookup of the Melbourne Cricket Ground took 8 seconds.

To find a place, or to read only the videos Virlo already has tagged there ($0.05), use Places.

What it costs

You pay when a lookup starts. 1 credit is $0.01.

What happens	Price
A lookup starts	$0.50 (50 credits), for any `max_videos` up to 200
A `query` matches more than one place and you get the list	Free
The same place again within 6 hours, asking for as many posts or fewer	Free (`cached: true`, the earlier run)
Any `400` or `404`	Free
A lookup that fails	Refunded in full, shown as `credits_refunded`

The exact charge is in the X-Cost (dollars) and X-Credits-Used (credits) response headers.

POST/v1/satellite/place

Start a place lookup

Name the place in exactly one way. Sending none, or more than one, returns 400.

Cost per request:$0.50 per lookup started. A list of matching places is free, and so is a repeat within 6 hours that asks for as many posts or fewer.

Body parameters

Name
place_id
Type
string
Description
A Virlo place id, from GET /v1/places or a video's location.id.
Name
poi_id
Type
string
Description
TikTok's own numeric place id.
Name
query
Type
string
Description
A place name, or the place's TikTok link (https://www.tiktok.com/place/...), which names the place exactly. 2 to 500 characters. A name is matched against the places Virlo has stored. The lookup starts when the name picks out one stored TikTok place: one place named exactly that, and no other carrying the name. Any other match (several places with the name, or places that carry it inside a longer name) answers 200 with "status": "candidates" (up to 20, plus total) and cost nothing: send the one you want as place_id. Each candidate has id, poi_id, name, kind, locality, city, country, video_count (Virlo videos tagged there) and tiktok_video_count. source says where the candidates came from: virlo for stored places, tiktok_search when TikTok's own place search answered because no stored place has the name. A tiktok_search candidate Virlo has not stored has id: null: send its poi_id.
Name
max_videos
Type
integer
Description
Most posts to return, newest first, from 1 to 200. Default 100. The price is the same.

Trend analysis isn't available for places yet.

Request

POST

/v1/satellite/place

curl -X POST https://api.virlo.ai/v1/satellite/place \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Melbourne Cricket Ground", "max_videos": 50 }'

Response

{
  "data": {
    "job_id": "c8814bb7-452d-4bab-9ca2-f57eaf81a051",
    "status": "processing"
  }
}

GET/v1/satellite/place/status/:job_id

Check lookup status

Free. Check every 5 to 10 seconds until finalized is true (status is completed or failed). This check stops working after 24 hours; the saved run doesn't. The job_id is also the run_id.

Request

GET

/v1/satellite/place/status/:job_id

curl https://api.virlo.ai/v1/satellite/place/status/c8814bb7-452d-4bab-9ca2-f57eaf81a051 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "status": "processing",
    "finalized": false
  }
}

What you get back

Name
place
Type
object
Description
id (Virlo's, null if Virlo hasn't seen the place), poi_id, name, kind (venue or area), address, city, country_code, lat, lng, url, and video_count: TikTok's own count of posts tagged there, read on this lookup. video_count_source is page (the place's page) or search (TikTok's place search, when the page had no count). null when TikTok gives none.
Name
change
Type
object
Description
What's different from your team's previous lookup of this place. Details below.
Name
videos
Type
array
Description
The posts tagged at the place, newest first, in the same shape as a hashtag lookup. Each also has source: gateway (read fresh on this lookup), stored (Virlo already had it), or both, and counts_fresh: true when the post's views and engagement were read from TikTok on this lookup, false when they are from the day Virlo last saw the post.
Name
stats
Type
object
Description
Views, engagement, top creators, related hashtags and top sounds over the returned posts. Same fields as hashtag lookup stats. velocity (videos_per_week, the two 4-week averages and is_accelerating) counts the posts read from TikTok on this lookup: a ranked sample of the place, so read the numbers as posts per week in that sample. It also has comparable: true when those posts reach back eight weeks and max_videos cut no older posts off. Read velocity.is_accelerating only when comparable is true; it is false otherwise. Lookups saved before Nov 12 2026 have averages over every returned post. How a place is moving is in change.
Name
sources
Type
object
Description
How many returned posts came each way: gateway, stored, both. stored_refreshed is how many of the stored posts had their views and engagement read from TikTok again on this lookup.
Name
walk
Type
object
Description
How reading TikTok's list went: stop (end, no_new, max_pages, failed, or not_found), pages_read, posts_seen, and nearby_dropped (posts on a venue's list tagged at a nearby place, left out; an area keeps them).
Name
sample_quality
Type
object
Description
truncated_by_cap, pages_fetched, and note, as on other lookups.

A lookup is a wide sample, not every post ever tagged there. place.video_count can be far larger than videos: the Melbourne Cricket Ground counts 102,349 tagged posts and one lookup returned 50. TikTok ranks a place's posts rather than listing them by date, so the newest post returned can be weeks old on a big venue.

What changed since last time

Because the list isn't newest first, new activity shows up in two numbers, measured against your team's previous completed lookup of the same place in the last 120 days:

Name
video_count_change
Type
integer | null
Description
TikTok's tag count now minus the count on the previous lookup. null without both counts.
Name
new_since_previous
Type
integer | null
Description
Posts this lookup saw that the previous one didn't. It can include older posts TikTok hadn't shown before, so check their publish_date before calling them new. new_since_previous_ids lists up to 50, matching videos[].id when they were kept.
Name
previous_run_id, previous_run_at, days_since_previous
Type
string, string, number
Description
Which lookup this is compared with, and how long ago.
Name
video_count, previous_video_count
Type
integer | null
Description
The two counts behind the change.

On a first lookup every field except video_count is null: there's nothing to compare yet, which isn't the same as no change. A repeat within 6 hours returns the earlier run, so look again after that.

Re-read past runs

Every paid lookup is saved as its own run. Reopening it is free, with the same tools as other lookups:

GET /v1/satellite/runs/:run_id: the full saved result, under result.
GET /v1/satellite/runs?type=place_lookup: your past place lookups.
GET /v1/satellite/runs/:run_id/posts: the posts, a page at a time.
GET /v1/satellite/runs/:run_id/compare: this run against an earlier one, including TikTok's tag count. Free.
POST /v1/satellite/runs/:run_id/refresh: run the same lookup again for $0.50.

Errors

Rejected requests cost nothing. A started lookup is billed, and refunded in full if it ends failed.

Name
400 Bad Request
Description
Not exactly one of place_id, poi_id and query, a bad value, an unknown field, or an Instagram place. Code validation_error.
Name
401 Unauthorized
Description
Key missing (missing_api_key), or wrong or revoked (invalid_api_key). See Authentication.
Name
402 Payment Required
Description
Balance under $0.50 when a lookup would start. required_credits is in credits (50 = $0.50).
Name
404 Not Found
Description
No such place, no TikTok place matches the name, or a status check for a job that is unknown or over 24 hours old. Open the saved run instead.
Name
429 Too Many Requests
Description
Over the limit. Code rate_limit_exceeded.
Name
502 Bad Gateway
Description
Virlo couldn't start the lookup. Code upstream_error. Retry after a short wait.

A lookup that starts and then fails ends with "status": "failed" and error on the status check, and the $0.50 comes back as credits_refunded. For example, TikTok doesn't know the place, or its page can't be read right now.