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

# Create task

> Create a billed asynchronous Entity Search task.

Creates an Entity Search task and returns a `leads_search_id` for later [Status](/api-reference/entity-search/status) and [Fetch](/api-reference/entity-search/fetch) calls.

`Idempotency-Key` is required and must contain 1 to 128 characters. The complete JSON body must be at most 1 MiB; unknown fields and multiple JSON objects are rejected.

## Example

```bash theme={null}
curl "https://app.lev8.com/v1/entity-search/create_task" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "x-api-key: $LEV8_API_KEY" \
  --header "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  --data '{
    "entity_type": "company",
    "objective": "AI startups that raised Series A in 2024",
    "limit": 20,
    "enrich_fields": ["funding stage", "headcount"]
  }'
```

## Response

```json theme={null}
{
  "object": "entity_search_task",
  "leads_search_id": "leads_search_01JABCDEF123456789",
  "entity_type": "company",
  "objective": "AI startups that raised Series A in 2024",
  "limit": 20,
  "status": "created",
  "created_at": "2026-08-04T00:00:00Z"
}
```

The response includes `X-Request-Id` and `Cache-Control: no-store`. Store the request ID, task ID, and idempotency key with your local job.

Repeating the same body with the same API key and idempotency key returns the existing task without reserving credits again. Reusing the key with different input returns `409 idempotency_error`; replaying while task creation has no stable handle returns `409 request_in_progress`.

See [Entity Search](/api-reference/entity-search) for entity types, field limits, deduplication, enrichment, and web search guidance.


## OpenAPI

````yaml POST /v1/entity-search/create_task
openapi: 3.1.0
info:
  title: lev8 API
  version: '1.0'
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://app.lev8.com
security:
  - ApiKeyAuth: []
paths:
  /v1/entity-search/create_task:
    post:
      summary: Create task
      description: Create an asynchronous Entity Search task.
      operationId: createEntitySearchTask
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: Stable key for this logical task, from 1 to 128 characters.
          schema:
            type: string
            minLength: 1
            maxLength: 128
            x-default: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitySearchCreateTaskRequest'
            example:
              entity_type: company
              objective: AI startups that raised Series A in 2024
              limit: 20
              enable_web_search: false
              enrich_fields:
                - funding stage
                - headcount
              dedup_lev8_leads: []
              dedup_custom_leads: []
      responses:
        '200':
          description: Task created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySearchTask'
        '401':
          description: Missing or invalid API key.
        '402':
          description: Insufficient credits.
        '403':
          description: API key is forbidden or lacks Entity Search access.
        '409':
          description: Idempotency conflict or task creation is still unresolved.
        '422':
          description: Validation failed.
        '429':
          description: Active-task concurrency limit reached.
        '500':
          description: Server error.
        '503':
          description: Entity Search or pricing is not enabled.
components:
  schemas:
    EntitySearchCreateTaskRequest:
      type: object
      additionalProperties: false
      required:
        - entity_type
        - objective
      properties:
        entity_type:
          type: string
          enum:
            - person
            - company
            - twitter_creator
            - youtube_creator
            - tiktok_creator
            - instagram_creator
            - shopify_store
          x-default: company
          example: company
        objective:
          type: string
          minLength: 1
          description: >-
            Natural-language objective, at most 4,000 UTF-8 bytes after
            trimming.
          x-default: AI startups that raised Series A in 2024
          example: AI startups that raised Series A in 2024
        limit:
          type: integer
          minimum: 1
          maximum: 500
          default: 20
          x-default: 20
          example: 20
        enable_web_search:
          type: boolean
          default: false
          x-default: false
          example: false
        enrich_fields:
          type:
            - array
            - 'null'
          items:
            type: string
          maxItems: 20
          x-default:
            - funding stage
            - headcount
          example:
            - funding stage
            - headcount
        dedup_lev8_leads:
          type: array
          maxItems: 100
          items:
            type: string
          x-default: []
          example: []
        dedup_custom_leads:
          type: array
          maxItems: 1000
          items:
            type: string
          x-default: []
          example: []
    EntitySearchTask:
      type: object
      properties:
        object:
          type: string
          const: entity_search_task
        leads_search_id:
          type: string
          example: leads_search_01JABCDEF123456789
        entity_type:
          type: string
          example: company
        objective:
          type: string
          example: AI startups that raised Series A in 2024
        limit:
          type: integer
          example: 20
        status:
          type: string
          example: created
        created_at:
          type: string
          format: date-time
          example: '2026-08-04T00:00:00Z'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      x-default: lev8_live_...

````