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

# Run a waterfall task

> Executes a waterfall task with the provided parameters and enrichments. The enrichments field specifies which data providers to use for the waterfall. Please note: data is stored in our systems for 24 hours. After 24 hours, all data and requests made via enrichments and waterfalls will be removed and your request id will no longer be active.

<Warning>
  This endpoint is **asynchronous**. It returns a `task_id` — poll [Get task status](/api-reference/endpoint/tasks-get-status) to retrieve your results. Task data expires after **24 hours**.
</Warning>


## OpenAPI

````yaml POST /v1/waterfalls/{waterfall_identifier}/run
openapi: 3.1.0
info:
  title: Databar.ai API
  description: >-

    # Authentication


    Databar uses API keys to allow access to the API. You can find your API key
    in your workspace home page, but to use the REST API you’ll first need to
    schedule a call with us.

    Our API expects the API key to be included in all API requests to the server
    in the Header of your request with the key `x-apikey`.

    To find your API key, head over to your Databar workspace and click
    Integrations.


    **Example:**


    `bash

    curl https://api.databar.ai/v1/user/me -H x-apikey: {YOUR_API_KEY}`
  contact:
    email: info@databar.ai
  version: 0.1.2
servers:
  - url: https://api.databar.ai
    description: Production
security: []
paths:
  /v1/waterfalls/{waterfall_identifier}/run:
    post:
      tags:
        - Waterfall
      summary: Run a waterfall task
      description: >-
        Executes a waterfall task with the provided parameters and enrichments.
        The enrichments field specifies which data providers to use for the
        waterfall. Please note: data is stored in our systems for 24 hours.
        After 24 hours, all data and requests made via enrichments and
        waterfalls will be removed and your request id will no longer be active.
      operationId: run_v1_waterfalls__waterfall_identifier__run_post
      parameters:
        - name: waterfall_identifier
          in: path
          required: true
          schema:
            type: string
            description: The identifier of the waterfall to run
            title: Waterfall Identifier
          description: The identifier of the waterfall to run
        - name: x-apikey
          in: header
          required: true
          schema:
            title: API Key
            description: API Key for authentication
          description: API Key for authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/app__api__v1__waterfall__Request'
            examples:
              email_getter:
                summary: Email finder waterfall
                description: Find email using first name, last name and company
                value:
                  params:
                    first_name: John
                    last_name: Doe
                    company: example.com
                  enrichments:
                    - 833
                    - 966
                  email_verifier: 10
              person_getter:
                summary: Person finder waterfall
                description: Find person information using email
                value:
                  params:
                    email: john.doe@example.com
                  enrichments:
                    - 833
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__v1__waterfall__Task'
              example:
                task_id: 123e4567-e89b-12d3-a456-426614174000
                status: created
        '400':
          description: Invalid params
          content:
            application/json:
              example:
                detail:
                  param1:
                    - This field is required.
        '403':
          description: Forbidden access
          content:
            application/json:
              example:
                detail: Forbidden
        '404':
          description: Waterfall not found
        '406':
          description: Forbidden access
          content:
            application/json:
              example:
                detail: Check the number of remaining credits or the tariff plan.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    app__api__v1__waterfall__Request:
      properties:
        params:
          type: object
          title: Params
        enrichments:
          items:
            type: integer
          type: array
          minItems: 1
          title: Enrichments
          description: Select at least 1 enrichment
        email_verifier:
          anyOf:
            - type: integer
            - type: 'null'
          title: Email Verifier
      type: object
      required:
        - params
        - enrichments
      title: Request
    app__api__v1__waterfall__Task:
      properties:
        task_id:
          type: string
          title: Task Id
        status:
          type: string
          title: Status
      type: object
      required:
        - task_id
        - status
      title: Task
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````