v1.0
Powered by

GET /v1/bloggers/by-username/

Read-only creator lookup. Returns the blogger_information row for the calling organization if the creator is currently tracked, otherwise 404 BLOGGER_NOT_TRACKED. The endpoint does not auto-track, does not enqueue, and does not call platform APIs — it is purely a DB read.

To start tracking a new creator, use POST /v1/bloggers/track first and poll GET /v1/bloggers/jobs/{job_id} until succeeded.

📋 Overview

Property Value
Method GET
Endpoint https://api.influtics.com/v1/bloggers/by-username/{username}
Auth Required ✅ Yes
Credits Cost 0 credits

🔐 Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

📝 Request

Path Parameters

Parameter Type Required Description
username string ✅ Required Channel username. URL-encode any leading @ as %40 (e.g. %40alice).

Query Parameters

Parameter Type Required Description
platform string ❌ Optional Platform name: tiktok, instagram, youtube, vk (default: tiktok)

Example Request

curl -X GET "https://api.influtics.com/v1/bloggers/by-username/bar.films?platform=tiktok" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Leading @ must be URL-encoded as %40
curl -X GET "https://api.influtics.com/v1/bloggers/by-username/%40alice?platform=youtube" \
  -H "Authorization: Bearer YOUR_API_KEY"

📤 Response

200 OK — creator is tracked

{
  "success": true,
  "data": {
    "blogger": {
      "id": "b05cae01-...",
      "platform": "tiktok",
      "channel_username": "bar.films",
      "channel_id": "MS4wLjABAAAA...",
      "display_name": "Bar Films",
      "avatar_url": "https://...",
      "follower_count": 123456,
      "is_active": true,
      "last_fetched_at": "2026-08-18T22:00:00Z"
    }
  },
  "meta": {
    "processing_time_ms": 12,
    "request_id": "9f7e8d4c-..."
  }
}

blogger fields

Field Type Description
id string Internal blogger_information.id (UUID).
platform string One of instagram, tiktok, youtube, vk.
channel_username string \| null Username without @. null for YouTube creators imported from video URLs (backfill is best-effort — see Backend docs).
channel_id string Platform-native channel ID.
display_name string \| null Creator display name, if known.
avatar_url string \| null Profile photo URL, if known.
follower_count integer \| null Last known follower count, if known.
is_active boolean Whether tracking is currently active for your org.
last_fetched_at string \| null ISO 8601 timestamp when platform stats were last refreshed — not when this endpoint was called.

⚠️ Error Responses

All errors share the standard envelope { success: false, error: { code, message, request_id, ... } }. The table below lists every documented code and the conditions that trigger it.

Status code Trigger Additional error fields
400 VALIDATION_ERROR Empty or missing username path segment field: "username"
402 PAID_PLAN_REQUIRED Free-tier API key attempted the lookup upgrade_url
404 BLOGGER_NOT_TRACKED The creator is not currently tracked by your org —
404 NOT_FOUND The legacy GET /v1/bloggers/info path (no deprecation window) —
500 INTERNAL_ERROR Unexpected DB or service failure —

🔁 Migration from GET /v1/bloggers/info

The previous query-string form was removed entirely on 2026-08-20. There is no deprecation window — requests to the old path return 404 NOT_FOUND.

Legacy call New call
GET /v1/bloggers/info?username=bar.films&platform=tiktok GET /v1/bloggers/by-username/bar.films?platform=tiktok
GET /v1/bloggers/info?username=@bar.films&platform=tiktok GET /v1/bloggers/by-username/%40bar.films?platform=tiktok
GET /v1/bloggers/info?username=new_creator (auto-tracking on miss) POST /v1/bloggers/track first, then poll GET /v1/bloggers/jobs/{job_id}

📌 Notes

  • The endpoint charges 0 credits because it does not call any platform API.
  • The response is scoped to the calling organization — a creator tracked by a different org returns 404 BLOGGER_NOT_TRACKED.
  • last_fetched_at is the last time platform stats were refreshed, not the last time this endpoint was called.

© Influtics