> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze Account

> Analyze a social media account and extract insights

## Overview

This endpoint analyzes a social media account by scraping their profile, videos, and generating analytics. The analysis includes engagement metrics, content keywords, popular hashtags, and more.

### Request Body

<ParamField body="username" type="string" required>
  The account username (without the @ symbol). Will be normalized automatically.
</ParamField>

<ParamField body="platform" type="string" required>
  The platform to analyze:

  * `tiktok`: Analyze a TikTok account
  * `youtube`: Analyze a YouTube account
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="message" type="string">
  Status message
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="account" type="object">
      The analyzed account with full details

      <Expandable title="account">
        <ResponseField name="id" type="string">
          Internal account ID
        </ResponseField>

        <ResponseField name="username" type="string">
          Account username
        </ResponseField>

        <ResponseField name="platform" type="string">
          Platform (tiktok or youtube)
        </ResponseField>

        <ResponseField name="displayName" type="string">
          Display name
        </ResponseField>

        <ResponseField name="bio" type="string">
          Account bio
        </ResponseField>

        <ResponseField name="avatarUrl" type="string">
          Profile picture URL
        </ResponseField>

        <ResponseField name="isVerified" type="boolean">
          Verification status
        </ResponseField>

        <ResponseField name="stats" type="object">
          Follower/following counts, videos, likes
        </ResponseField>

        <ResponseField name="analytics" type="object">
          Engagement rate, virality score, average views
        </ResponseField>

        <ResponseField name="topHashtags" type="array">
          Most used hashtags
        </ResponseField>

        <ResponseField name="keywords" type="array">
          Extracted content keywords
        </ResponseField>

        <ResponseField name="lastAnalyzed" type="string">
          Analysis timestamp
        </ResponseField>

        <ResponseField name="profileUrl" type="string">
          Link to the profile
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.hooked.so/v1/social/account/analyze" \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "username": "fitnessguru",
      "platform": "tiktok"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.hooked.so/v1/social/account/analyze', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      username: 'fitnessguru',
      platform: 'tiktok'
    })
  });

  const data = await response.json();
  console.log(data.data.account);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.hooked.so/v1/social/account/analyze',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'username': 'fitnessguru',
          'platform': 'tiktok'
      }
  )

  account = response.json()['data']['account']
  print(f"Analyzed {account['displayName']} with {account['stats']['followers']} followers")
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Account analyzed successfully",
    "data": {
      "account": {
        "id": "clx123abc",
        "username": "fitnessguru",
        "platform": "tiktok",
        "displayName": "Fitness Guru",
        "bio": "Helping you get fit one video at a time",
        "avatarUrl": "https://cdn.tiktok.com/avatar.jpg",
        "isVerified": true,
        "stats": {
          "followers": 1500000,
          "following": 250,
          "videos": 342,
          "likes": 45000000
        },
        "analytics": {
          "engagementRate": 12.5,
          "viralityScore": 78.3,
          "avgViews": 890000
        },
        "topHashtags": ["fitness", "workout", "gym"],
        "keywords": ["fitness", "exercise", "motivation"],
        "lastAnalyzed": "2024-01-15T10:30:00Z",
        "createdAt": "2024-01-15T10:30:00Z",
        "profileUrl": "https://www.tiktok.com/@fitnessguru"
      }
    }
  }
  ```
</ResponseExample>

## Error Handling

<AccordionGroup>
  <Accordion title="Account already analyzed" icon="exclamation-triangle">
    If the account has already been analyzed, you'll receive a 400 error. Use the [Refresh Account](/api-reference/social/account-refresh) endpoint to update existing accounts.

    ```json theme={null}
    {
      "success": false,
      "message": "Account already analyzed. Use refresh endpoint to update."
    }
    ```
  </Accordion>

  <Accordion title="Account not found" icon="user-slash">
    If the username doesn't exist on the platform:

    ```json theme={null}
    {
      "success": false,
      "message": "Account not found: username"
    }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  Analysis may consume API credits depending on the depth of data scraped.
</Note>


## OpenAPI

````yaml POST /v1/social/account/analyze
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
paths:
  /v1/social/account/analyze:
    post:
      tags:
        - Social Accounts
      summary: Analyze Account
      description: Analyze a social media account and extract insights
      operationId: analyzeSocialAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - platform
              properties:
                username:
                  type: string
                platform:
                  type: string
                  enum:
                    - tiktok
                    - youtube
      responses:
        '201':
          description: Account analyzed successfully
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````