> ## 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:
                error: INVALID_PARAMS
                detail: 'Row 1: param1: This field is required.'
                rows:
                  - position: 1
                    fields:
                      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
          title: Enrichments
          description: >-
            Provider IDs to run, in order. Omit or pass [] to run the
            waterfall's default cascade (providers with
            enabled_by_default=true).
        email_verifier:
          anyOf:
            - type: integer
            - type: 'null'
          title: Email Verifier
      type: object
      required:
        - params
      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:
        error:
          type: string
          title: Error
          description: VALIDATION_ERROR
        detail:
          type: string
          title: Detail
          description: Human-readable summary, one problem per field joined by '; '.
        fields:
          type: array
          title: Fields
          items:
            type: object
            properties:
              loc:
                items:
                  type: string
                type: array
              msg:
                type: string
            required:
              - loc
              - msg
      type: object
      required:
        - error
        - detail
      title: HTTPValidationError

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.