Adds a keyword to the daily tracking list. Once tracked, the background scraping pipeline will periodically fetch search rankings for this keyword, building historical data that powers the Keyword Trends endpoint.
Request Body
{
"keyword": "puzzle game"
}
| Field | Type | Required | Description |
|---|
| keyword | string | Yes | Keyword to track (min 2 characters) |
Code Examples
curl -X POST "https://api.appeeky.com/v1/keywords/track" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword": "puzzle game"}'
Response
Status: 201 Created
{
"data": {
"keyword": "puzzle game",
"message": "Keyword added to tracking list"
}
}
| Field | Type | Description |
|---|
| keyword | string | The tracked keyword |
| message | string | Confirmation message |
Idempotent upsert: If the keyword already exists in the tracking list, it is updated to active status. You can safely call this endpoint multiple times for the same keyword without creating duplicates.
Auto-tracking: Keywords are also automatically added to the tracking pipeline when you use GET /v1/keywords/ranks and a live iTunes Search fallback is triggered. If you’re already using the ranks endpoint for keyword research, many of your keywords will be tracked automatically — no need to call this endpoint separately for those.
Errors
| Status | Code | When |
|---|
| 400 | INVALID_KEYWORD | Keyword shorter than 2 characters |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 429 | RATE_LIMITED | Too many requests — slow down |
| 500 | DB_ERROR | Database operation failed |
