> ## 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.

# Create Search

> Create a new search and scrape videos matching the search term

## Overview

This endpoint creates a new search by scraping videos from the specified platform that match your search term. The results are saved and can be retrieved later.

### Request Body

<ParamField body="searchTerm" type="string" required>
  The search query (1-200 characters). Will be trimmed automatically.
</ParamField>

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

  * `tiktok`: Search TikTok
  * `youtube`: Search YouTube
</ParamField>

<ParamField body="limit" type="number" default="20">
  Maximum number of videos to scrape (1-50)
</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="search" type="object">
      The created search with aggregated analytics
    </ResponseField>

    <ResponseField name="videosFound" type="number">
      Number of videos scraped
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.hooked.so/v1/social/search/create" \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "searchTerm": "fitness motivation",
      "platform": "tiktok",
      "limit": 25
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.hooked.so/v1/social/search/create', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      searchTerm: 'fitness motivation',
      platform: 'tiktok',
      limit: 25
    })
  });

  const data = await response.json();
  console.log(`Found ${data.data.videosFound} videos`);
  ```

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

  response = requests.post(
      'https://api.hooked.so/v1/social/search/create',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'searchTerm': 'fitness motivation',
          'platform': 'tiktok',
          'limit': 25
      }
  )

  result = response.json()
  print(f"Found {result['data']['videosFound']} videos")
  print(f"Avg views: {result['data']['search']['analytics']['avgViews']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Search created successfully",
    "data": {
      "search": {
        "id": "clx123abc",
        "searchTerm": "fitness motivation",
        "platform": "tiktok",
        "totalResults": 25,
        "analytics": {
          "avgViews": 1250000,
          "avgLikes": 89000,
          "avgComments": 1200,
          "avgShares": 5600,
          "engagementRate": 7.8
        },
        "topHashtags": ["fitness", "motivation", "workout", "gym"],
        "keywords": [],
        "keywordsStatus": "pending",
        "lastSearched": "2024-01-15T10:30:00Z",
        "createdAt": "2024-01-15T10:30:00Z"
      },
      "videosFound": 25
    }
  }
  ```
</ResponseExample>

## Notes

<Note>
  If a search with the same term and platform already exists, it will be updated with fresh results rather than creating a duplicate.
</Note>

<Note>
  Keyword extraction runs asynchronously. Check the `keywordsStatus` field to see if processing is complete.
</Note>

<Warning>
  Creating searches consumes API credits based on the number of videos scraped.
</Warning>


## OpenAPI

````yaml POST /v1/social/search/create
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/search/create:
    post:
      tags:
        - Social Search
      summary: Create Search
      description: Create a new search and scrape videos matching the search term
      operationId: createSocialSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - searchTerm
                - platform
              properties:
                searchTerm:
                  type: string
                platform:
                  type: string
                  enum:
                    - tiktok
                    - youtube
                limit:
                  type: integer
                  default: 20
      responses:
        '201':
          description: Search created successfully
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````