# GET /v1/bloggers/by-username/{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`](./track) first and poll [`GET /v1/bloggers/jobs/{job_id}`](./jobs) 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

```bash
curl -X GET "https://api.influtics.com/v1/bloggers/by-username/bar.films?platform=tiktok" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
# 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

```json
{
  "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](../../../../influtics-backend/influtics-workers/shared/services/CLAUDE.md#rule-youtube-channel_username-backfill)). |
| `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.