Suggestions (hashtags & keywords)

What to tag a post with, and what people search around the word you are writing about. Two answers to the same question — what should this caption say to be found — so they are one endpoint with a type, not two URLs.

Like /audience, /comments and /post-analytics, this is one endpoint per question with a platform telling it which network to ask. Adding a network never changes your integration.

• Method: GET
• Endpoint: /api/uploadposts/suggestions
• Authentication:
  • API Key in the Authorization header.
    • Authorization: Apikey <YOUR_API_KEY>

Query Parameters

Parameter	Type	Required	Description	Default
platform	string	Yes	The network to ask. Today only tiktok answers; anything else is a 400 naming the platforms that do.	-
user	string	Yes	The profile's username. Must have an account of that platform connected.	-
type	string	No	hashtags — the tags to pair with a keyword. keywords — what people search around it.	hashtags
q	string	Yes	The seed keyword.	-
country_code	string	No	ISO 3166-1 alpha-2 country to rank the suggestions for (e.g. ES, US, MX). Applies to type=hashtags.	the platform's own default
language	string	No	Language code for the suggestions (e.g. es, en). Applies to type=hashtags.	the platform's own default

type=keywords needs a reconnected account

On TikTok, search permission is granted at the moment the account is connected, so only a reconnected account reports trend_search in its capabilities. type=hashtags works on any recently connected account; type=keywords answers 400 with error_code: "tiktok_reconnect_required" until its owner reconnects it from Manage Users.

---

type=hashtags

Given a keyword, the hashtags the platform suggests pairing with it and how many times content carrying each one has been viewed.

curl -G 'https://api.upload-post.com/api/uploadposts/suggestions' \
  -H 'Authorization: Apikey your-api-key-here' \
  -d 'platform=tiktok' \
  -d 'user=your_profile' \
  -d 'type=hashtags' \
  --data-urlencode 'q=instant camera' \
  -d 'country_code=ES' \
  -d 'language=es'

Successful Response (200 OK)

{
  "success": true,
  "platform": "tiktok",
  "type": "hashtags",
  "query": "instant camera",
  "hashtags": [
    { "name": "instantcamera", "view_count": 1284000000 },
    { "name": "polaroid", "view_count": 128970043215 },
    { "name": "analogphotography", "view_count": 742000000 },
    { "name": "camarainstantanea", "view_count": 31400000 }
  ]
}

Field	Description
query	The keyword you asked for, echoed back.
hashtags[].name	The tag without the leading #. Add it yourself when writing the caption.
hashtags[].view_count	Lifetime views of content carrying that tag. It reaches 12 digits on the big tags, so parse it as a 64-bit integer — a 32-bit one overflows.

An empty hashtags array is a valid answer: there is nothing to suggest for that keyword in that country/language combination. Try a broader keyword or drop country_code.

---

type=keywords

What people actually search around the word you give it. Use it before writing a caption: it tells you which phrasing has demand, instead of guessing which of five synonyms your audience types.

curl -G 'https://api.upload-post.com/api/uploadposts/suggestions' \
  -H 'Authorization: Apikey your-api-key-here' \
  -d 'platform=tiktok' \
  -d 'user=your_profile' \
  -d 'type=keywords' \
  --data-urlencode 'q=instant camera'

Successful Response (200 OK)

{
  "success": true,
  "platform": "tiktok",
  "type": "keywords",
  "query": "instant camera",
  "keywords": [
    { "keyword": "instant camera", "search_volume": 184000 },
    { "keyword": "instant camera film", "search_volume": 61200 },
    { "keyword": "best instant camera 2026", "search_volume": 24700 },
    { "keyword": "instant camera aesthetic", "search_volume": 9800 }
  ]
}

Field	Description
keywords	The search terms, passed through as the platform returns them. Treat each object as an open shape: fields can be added at any time.

---

Error Responses

• 400 Bad Request — the platform does not answer this question yet.

{
  "success": false,
  "message": "'instagram' does not support suggestions yet. Supported: tiktok.",
  "error_code": "platform_not_supported"
}

• 400 Bad Request — a missing q or platform, or a type outside the two values.

{
  "success": false,
  "message": "type must be one of: hashtags, keywords",
  "error_code": "invalid_parameter"
}

• 400 Bad Request — type=keywords on a connection that never granted search permission. Reconnect the account.

{
  "success": false,
  "message": "This TikTok connection has not granted the permission this needs. Reconnect your TikTok account from Manage Users (https://app.upload-post.com/manage-users).",
  "error_code": "tiktok_reconnect_required"
}

• 404 Not Found — no profile with that username exists under your API key (error_code: "PROFILE_NOT_FOUND").
• 409 Conflict — the token expired and the account must be reconnected ("reauth_required": true).
• 502 Bad Gateway — the platform rejected the lookup; its message is returned verbatim in message.

Additional Notes

• The two types compose: run type=keywords to pick the phrasing people search for, then type=hashtags on the winning term to pick the tags that carry it.
• Suggestions are not personalised to the account. The connection is what authorises the call, not what shapes the answer.

---

Related

• Audience Insights — who follows the account and when they are online.
• Upload Video — where the caption you are writing ends up.
• Character limits — how much caption each platform accepts.