# Add a column to a table
Source: https://docs.databar.ai/api-reference/endpoint/columns-create
POST /v1/table/{table_uuid}/columns
Create a new column on a table. Type defaults to 'text'.
# Delete a column from a table
Source: https://docs.databar.ai/api-reference/endpoint/columns-delete
DELETE /v1/table/{table_uuid}/columns/{column_id}
Delete a column from a table by its UUID.
# Rename a column
Source: https://docs.databar.ai/api-reference/endpoint/columns-rename
PATCH /v1/table/{table_uuid}/columns/{column_id}
Rename an existing column on a table.
# Create a custom API connector
Source: https://docs.databar.ai/api-reference/endpoint/connectors-create
POST /v1/connectors/
Registers a new custom HTTP API endpoint as a connector in your workspace. Once created the connector appears as an enrichment/exporter you can use in tables.
# Delete custom connector
Source: https://docs.databar.ai/api-reference/endpoint/connectors-delete
DELETE /v1/connectors/{connector_id}
Permanently removes a custom API connector and its associated data.
# Get custom connector info
Source: https://docs.databar.ai/api-reference/endpoint/connectors-get
GET /v1/connectors/{connector_id}
Retrieve details of a specific custom API connector.
# List custom API connectors
Source: https://docs.databar.ai/api-reference/endpoint/connectors-list
GET /v1/connectors/
Returns all custom API connectors configured in your workspace.
# Update custom connector
Source: https://docs.databar.ai/api-reference/endpoint/connectors-update
PUT /v1/connectors/{connector_id}
Replaces the configuration of an existing custom API connector.
# Run bulk enrichment
Source: https://docs.databar.ai/api-reference/endpoint/enrichments-bulk-run
POST /v1/enrichments/{enrichment_id}/bulk-run
Submits a bulk enrichment run for the specified enrichment ID.
**Pricing:** for enrichments with `pricing.type == "per_parameter"`, the cost per request is `price × params[pricing.parameter]`. Check `GET /v1/enrichments/{id}` to see the pricing details.
This runs an enrichment in bulk **headless** — results are returned inline. To enrich rows stored in a Databar table, see [Run table enrichment](/api-reference/endpoint/tables-run-enrichment).
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**.
Results are **aligned to your inputs**: the `data` array has one element per
input, in the same order you submitted them, with `null` for inputs that
returned no data. So `len(data)` equals the number of inputs and `data[i]` is
the result for input `i` — join results back to inputs by position.
# Get a specific enrichment
Source: https://docs.databar.ai/api-reference/endpoint/enrichments-get
GET /v1/enrichments/{enrichment_id}
Retrieve detailed information about a specific enrichment by its ID.
# Get available enrichments
Source: https://docs.databar.ai/api-reference/endpoint/enrichments-list
GET /v1/enrichments/
Retrieves enrichments available on Databar. Use the search parameter to filter results by keyword.
**Pagination:** pass `page` to receive a paginated envelope (`{items, page, limit, has_next_page, total_count}`).
**⚠️ Deprecated:** calling without `page` returns a plain JSON array for backward compatibility. This form will be removed in a future version — always pass `page` for new integrations.
# Get choices for a parameter
Source: https://docs.databar.ai/api-reference/endpoint/enrichments-param-choices
GET /v1/enrichments/{enrichment_id}/params/{param_slug}/choices
Returns paginated choices for a select/mselect parameter. Use the `q` parameter to search, and `page`/`limit` for pagination.
# Run single enrichment
Source: https://docs.databar.ai/api-reference/endpoint/enrichments-run
POST /v1/enrichments/{enrichment_id}/run
Executes an enrichment task with the provided parameters.
**Pricing:** for enrichments with `pricing.type == "per_parameter"`, the cost per request is `price × params[pricing.parameter]`. Check `GET /v1/enrichments/{id}` to see the pricing details.
This runs an enrichment **headless** — you get results inline without storing them in a table. To run an enrichment against rows in a Databar table, see [Run table enrichment](/api-reference/endpoint/tables-run-enrichment).
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**.
# Get a specific exporter
Source: https://docs.databar.ai/api-reference/endpoint/exporters-get
GET /v1/exporters/{exporter_id}
Retrieve detailed information about a specific exporter by its ID, including its input parameters and output fields.
# Get available exporters
Source: https://docs.databar.ai/api-reference/endpoint/exporters-list
GET /v1/exporters/
Retrieves exporters (CRM/destination integrations) available on Databar.
**Pagination:** pass `page` to receive a paginated envelope (`{items, page, limit, has_next_page, total_count}`).
**Deprecated:** calling without `page` returns a plain JSON array for backward compatibility. This form will be removed in a future version -- always pass `page` for new integrations.
# Get a workspace flow
Source: https://docs.databar.ai/api-reference/endpoint/flows-get
GET /v1/flows/{flow_id}
Retrieve a single flow by its numeric ID. Use the returned `inputs` array to discover the required parameter names when calling `POST /v1/flows/{flow_id}/run`.
# List workspace flows
Source: https://docs.databar.ai/api-reference/endpoint/flows-list
GET /v1/flows/
Returns all flows defined in your workspace, ordered by most recently updated.
# Run a flow
Source: https://docs.databar.ai/api-reference/endpoint/flows-run
POST /v1/flows/{flow_id}/run
Start a flow execution and return a `task_id`. Poll `GET /v1/tasks/{task_id}` to check status and retrieve outputs. Inputs are passed as `{input_id: value}` — use `GET /v1/flows/{flow_id}` to discover the declared inputs.
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**.
# Create a folder
Source: https://docs.databar.ai/api-reference/endpoint/folders-create
POST /v1/folders
Create a new folder to organize tables.
# Delete a folder
Source: https://docs.databar.ai/api-reference/endpoint/folders-delete
DELETE /v1/folders/{folder_id}
Delete a folder. Tables in the folder are NOT deleted, they are moved to the root level.
# List all folders
Source: https://docs.databar.ai/api-reference/endpoint/folders-list
GET /v1/folders
List all folders in your workspace.
# Move a table into or out of a folder
Source: https://docs.databar.ai/api-reference/endpoint/folders-move-table
POST /v1/folders/move-table
Move a table into a folder, or remove it from its current folder.
Pass `folder_id: null` (or omit it) to remove the table from any folder.
# Rename a folder
Source: https://docs.databar.ai/api-reference/endpoint/folders-rename
PATCH /v1/folders/{folder_id}
Rename an existing folder.
# Delete rows from table
Source: https://docs.databar.ai/api-reference/endpoint/rows-delete
POST /v1/table/{table_uuid}/rows/delete
Delete specific rows from a table by their UUIDs.
# Get table rows
Source: https://docs.databar.ai/api-reference/endpoint/rows-get
GET /v1/table/{table_uuid}/rows
Get rows from a table with pagination and optional filtering.
**Filtering:** Use the `filter` query parameter with a JSON-encoded object. Keys are column names, values are objects with one operator.
**Operators:**
- `equals` — exact match
- `contains` — substring match (case-insensitive)
- `not_equals` — excludes exact match
- `is_empty` — column value is null (pass `true`)
- `is_not_empty` — column value is not null (pass `true`)
Multiple column filters use AND logic.
**Examples:**
- `?filter={"company":{"equals":"OpenAI"}}`
- `?filter={"name":{"contains":"Data"}}`
- `?filter={"name":{"contains":"a"},"revenue":{"equals":"5000"}}`
- `?filter={"email":{"is_not_empty":true}}`
# Add rows to table
Source: https://docs.databar.ai/api-reference/endpoint/rows-insert
api-reference/openapi.json POST /v1/table/{table_uuid}/rows
Add rows to a table in batch. Uses human-readable column names.
**options.allow_new_columns** — when `true`, any column name in `fields` that doesn't exist yet will be auto-created as a text column.
**options.dedupe** — when `enabled: true`, rows whose `keys` columns match an existing row are skipped (`action: skipped_duplicate`) instead of inserted.
# Update rows in table by ID
Source: https://docs.databar.ai/api-reference/endpoint/rows-update
api-reference/openapi.json PATCH /v1/table/{table_uuid}/rows
Update specific fields in multiple rows at once. Uses human-readable column names.
**overwrite** controls whether existing non-empty values are replaced:
- `true` (default) — always set the new value.
- `false` — only fill in fields that are currently empty.
If a row UUID is not found the result entry will contain `"ok": false` with an error object `{"code": "ROW_NOT_FOUND"}`.
# Upsert rows by key values
Source: https://docs.databar.ai/api-reference/endpoint/rows-upsert
api-reference/openapi.json POST /v1/table/{table_uuid}/rows/upsert
For each row, match on a single **key** column:
- **0 matches** → a new row is created (`action: created`).
- **1 match** → the existing row is updated (`action: updated`).
- **>1 matches** → returns an `AMBIGUOUS_MATCH` error for that row.
The `key` dict must contain exactly one entry `{column_name: value}`.
**Upsert = update or create.** Rows are matched by the key columns you specify. If a matching row exists, it is updated; otherwise a new row is inserted.
# Add enrichment to table
Source: https://docs.databar.ai/api-reference/endpoint/tables-add-enrichment
POST /v1/table/{table_uuid}/add-enrichment
Add an enrichment to a table by its UUID.
## Mapping format
The `mapping` object links enrichment parameters to table columns (or hardcoded values).
Each key is an **enrichment parameter slug** (from `GET /v1/enrichments/{id}` → `params[].name`).
Each value is one of:
| Type | When to use | `value` field |
| ----------- | -------------------------------- | ------------------------------------------- |
| `"mapping"` | Read value from a column per row | Human-readable column name (e.g. `"email"`) |
| `"simple"` | Same static value for every row | The literal value (e.g. `"US"`) |
```json theme={null}
{
"enrichment": 123,
"mapping": {
"email": {
"type": "mapping",
"value": "email"
},
"country": {
"type": "simple",
"value": "US"
}
}
}
```
## After adding
The response body is `{}`. To get the **table-enrichment ID** required by `POST /v1/table/{table_uuid}/run-enrichment/{id}`, call:
```
GET /v1/table/{table_uuid}/enrichments
```
and use the `id` field of the newly added entry.
# Add exporter to table
Source: https://docs.databar.ai/api-reference/endpoint/tables-add-exporter
POST /v1/table/{table_uuid}/add-exporter
Add an exporter (CRM/destination) to a table by its UUID.
Use `GET /v1/exporters` to list available exporters and `GET /v1/exporters/{id}` to see required parameters.
After adding, run the exporter with `POST /v1/table/{uuid}/run-enrichment/{id}`.
# Add waterfall to table
Source: https://docs.databar.ai/api-reference/endpoint/tables-add-waterfall
POST /v1/table/{table_uuid}/add-waterfall
Add a waterfall to a table by its UUID. A waterfall tries multiple data providers in sequence until one returns a result.
Use `GET /v1/waterfalls` to list available waterfalls and their parameters, enrichments, and email verifiers.
After adding, run the waterfall with `POST /v1/table/{uuid}/run-enrichment/{id}`.
# Create a table
Source: https://docs.databar.ai/api-reference/endpoint/tables-create
POST /v1/table/create
Create a new table in your workspace. Optionally specify a name, column names, and number of empty rows. By default the table is created with columns column1/column2/column3 and 0 rows.
# Delete a table
Source: https://docs.databar.ai/api-reference/endpoint/tables-delete
DELETE /v1/table/{table_uuid}
Permanently delete a table and all its rows by UUID.
# Get table columns
Source: https://docs.databar.ai/api-reference/endpoint/tables-get-columns
GET /v1/table/{table_uuid}/columns
Get a tables columns by its ID.
# Get enrichments in table
Source: https://docs.databar.ai/api-reference/endpoint/tables-get-enrichments
GET /v1/table/{table_uuid}/enrichments
List all enrichments configured on a table. Returns enrichment IDs, parameter mappings, and status for each enrichment attached to the specified table.
# Get exporters in table
Source: https://docs.databar.ai/api-reference/endpoint/tables-get-exporters
GET /v1/table/{table_uuid}/exporters
Get all exporters installed on a table. Use the returned `id` with `POST /v1/table/{uuid}/run-enrichment/{id}` to run.
# Get waterfalls in table
Source: https://docs.databar.ai/api-reference/endpoint/tables-get-waterfalls
GET /v1/table/{table_uuid}/waterfalls
Get all waterfalls installed on a table. Use the returned `id` with `POST /v1/table/{uuid}/run-enrichment/{id}` to run.
# Get all workspace tables
Source: https://docs.databar.ai/api-reference/endpoint/tables-list
GET /v1/table/
Retrieves all tables currently in your workspace, including their name, created date, and identifiers.
# Rename a table
Source: https://docs.databar.ai/api-reference/endpoint/tables-rename
PATCH /v1/table/{table_uuid}
Rename a table by its UUID.
# Run enrichment in table
Source: https://docs.databar.ai/api-reference/endpoint/tables-run-enrichment
api-reference/openapi.json POST /v1/table/{table_uuid}/run-enrichment/{enrichment_id}
Run a specific enrichment or waterfall on a table.
Works for both enrichments (from `POST /v1/table/{uuid}/add-enrichment`) and waterfalls (from `POST /v1/table/{uuid}/add-waterfall`). Use the `id` returned when adding.
**run_strategy** controls which rows are processed:
- `run_all` (default) — run on every row.
- `run_empty` — only run on rows where the result is empty.
**row_ids** (optional) — list of specific row UUIDs to process. When provided, only those rows are processed (subject to run_strategy).
## enrichment\_id
The `enrichment_id` path parameter is the **table-enrichment ID** — the `id` returned by `GET /v1/table/{table_uuid}/enrichments`.
This is **not** the same as the enrichment catalog ID. You must first add the enrichment to the table via `POST /v1/table/{table_uuid}/add-enrichment`, then retrieve the table-enrichment ID from `GET /v1/table/{table_uuid}/enrichments`.
# Get task data or status
Source: https://docs.databar.ai/api-reference/endpoint/tasks-get-status
GET /v1/tasks/{task_id}
Retrieve the data (or results) of an enrichment run by the task id. If the request is still processing, the status field will show a 'processing' status, if the request is completed, your data will be returned in the 'data' key. The task_id is provided as a response when you launch an enrichment task.
# Get user info
Source: https://docs.databar.ai/api-reference/endpoint/user-me
GET /v1/user/me
Get information about your current account.
# Run bulk waterfall
Source: https://docs.databar.ai/api-reference/endpoint/waterfalls-bulk-run
POST /v1/waterfalls/{waterfall_identifier}/bulk-run
Submits a bulk waterfall run for the specified waterfall identifier with custom 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.
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**.
Results are **aligned to your inputs**: the `data` array has one element per
input, in the same order you submitted them, with `null` for inputs that
returned no data. So `len(data)` equals the number of inputs and `data[i]` is
the result for input `i` — join results back to inputs by position.
# Get a specific waterfall
Source: https://docs.databar.ai/api-reference/endpoint/waterfalls-get
GET /v1/waterfalls/{waterfall_identifier}
Retrieve detailed information about a specific waterfall by its identifier.
# Get available waterfalls
Source: https://docs.databar.ai/api-reference/endpoint/waterfalls-list
GET /v1/waterfalls/
Retrieves a list of all waterfalls available on Databar.
# Run a waterfall task
Source: https://docs.databar.ai/api-reference/endpoint/waterfalls-run
POST /v1/waterfalls/{waterfall_identifier}/run
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.
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**.
# Introduction
Source: https://docs.databar.ai/api-reference/introduction
Databar.ai REST API reference
## Authentication
Databar uses API keys to allow access to the API. Include your key in the `x-apikey` header on every request.
```bash theme={null}
curl https://api.databar.ai/v1/user/me \
-H "x-apikey: YOUR_API_KEY"
```
To find your API key, head over to your [Databar workspace](https://databar.ai) and click **Integrations**.
## Base URL
All API requests should be made to:
```
https://api.databar.ai
```
## Async Pattern
Some operations (bulk enrichments, waterfalls) run asynchronously. The flow is:
Call a run or bulk-run endpoint. You'll receive a `task_id` in the response.
Call `GET /v1/tasks/{task_id}` with the `task_id`. The `status` field will be `processing`, `completed`, or `failed`.
When `status` is `completed`, the `data` field contains your results. For
bulk runs, `data` is aligned to your inputs: one element per input, in the
same order you submitted them, with `null` for inputs that returned no data
(so `len(data)` equals the number of inputs and `data[i]` is the result for
input `i`). A single (non-bulk) run returns the result object directly.
Data from enrichment and waterfall tasks is stored for **24 hours**. After that, the data is permanently deleted and the task status will return `gone`. Make sure to retrieve your results promptly.
## Pagination
The `GET /v1/table/{table_uuid}/rows` endpoint supports pagination:
| Parameter | Default | Description |
| ---------- | ------- | ---------------------------------- |
| `per_page` | 1000 | Number of rows to return per page. |
| `page` | 1 | Page number to retrieve. |
The response includes `has_next_page` and `total_count` to help you iterate.
## Error Handling
The API uses standard HTTP status codes. All error responses return a JSON body with a `detail` field describing the issue.
### Common Error Codes
| Code | Meaning | When it happens |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `400` | **Bad Request** | Invalid or missing parameters in your request. The response body shows which fields failed validation. |
| `403` | **Forbidden** | Your API key is missing, invalid, or doesn't have access to the requested resource. |
| `404` | **Not Found** | The enrichment, waterfall, table, or task ID you referenced doesn't exist. |
| `406` | **Insufficient Credits** | Your account doesn't have enough credits or your plan doesn't support this operation. |
| `410` | **Gone** | The requested data has expired. Task results are deleted after 24 hours. |
| `422` | **Validation Error** | The request body failed schema validation. The response includes field-level error details. |
### Error Response Formats
**Parameter validation error** (400):
```json theme={null}
{
"detail": {
"param1": ["This field is required."]
}
}
```
**Batch operation error** (400) — for row insert/update/upsert:
```json theme={null}
{
"error": "BATCH_TOO_LARGE",
"max_size": 50
}
```
Batch error codes: `BATCH_TOO_LARGE`, `UNKNOWN_COLUMNS`, `INVALID_DATA`.
**Insufficient credits** (406):
```json theme={null}
{
"detail": "Check the number of remaining credits or the tariff plan."
}
```
**Schema validation error** (422):
```json theme={null}
{
"detail": [
{
"loc": ["body", "params"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
```
# CLI Reference
Source: https://docs.databar.ai/cli
The Databar CLI lets you run enrichments, manage tables, and automate workflows directly from your terminal or AI agent.
## Installation
```bash theme={null}
pip install databar
```
After installing, the `databar` command is available in your terminal.
```bash theme={null}
databar --help
databar --version
```
***
## Authentication
```bash theme={null}
# Save your API key (prompted securely)
databar login
# Or pass it directly
databar login --api-key your-key-here
# Verify your key
databar whoami
```
Your key is saved to `~/.databar/config` with `600` permissions (owner read-only).
You can also set the `DATABAR_API_KEY` environment variable — it takes priority over the config file:
```bash theme={null}
export DATABAR_API_KEY=your-key-here
```
***
## Output formats
Every command supports `--format` with three options:
| Flag | Output | Best for |
| ---------------- | --------------------------------- | ---------------------------- |
| `--format table` | Rich terminal table (default) | Human viewing |
| `--format json` | Raw JSON to stdout | Piping, scripting, AI agents |
| `--format csv` | CSV to stdout or `--out file.csv` | Spreadsheets, data pipelines |
```bash theme={null}
# Pipe JSON output to jq
databar enrich list --format json | jq '.[].name'
# Save rows to CSV
databar table rows --format csv --out rows.csv
```
***
## Enrichments
```bash List enrichments theme={null}
databar enrich list
databar enrich list --query "linkedin"
databar enrich list --format json
```
```bash Get enrichment details theme={null}
# Shows parameters, response fields, pricing
databar enrich get 123
databar enrich get 123 --format json
```
```bash Run a single enrichment theme={null}
# Submits and polls until complete
databar enrich run 123 --params '{"email": "alice@example.com"}'
# JSON output (pipe-friendly)
databar enrich run 123 --params '{"email": "alice@example.com"}' --format json
# Raw result without formatting
databar enrich run 123 --params '{"email": "alice@example.com"}' --raw
```
```bash Bulk run from CSV theme={null}
# Input CSV must have column headers matching enrichment param names
databar enrich bulk 123 --input leads.csv
databar enrich bulk 123 --input leads.csv --format csv --out results.csv
```
```bash Get parameter choices theme={null}
# For select/multiselect parameters
databar enrich choices 123 country
databar enrich choices 123 country --query "united"
databar enrich choices 123 country --page 2 --limit 100
```
***
## Waterfalls
```bash List waterfalls theme={null}
databar waterfall list
databar waterfall list --query "email"
databar waterfall list --format json
```
```bash Get waterfall details theme={null}
databar waterfall get email_getter
databar waterfall get email_getter --format json
```
```bash Run a waterfall theme={null}
# Uses all available providers by default
databar waterfall run email_getter \
--params '{"linkedin_url": "https://linkedin.com/in/alice"}'
# Specify providers explicitly (comma-separated IDs)
databar waterfall run email_getter \
--params '{"linkedin_url": "https://linkedin.com/in/alice"}' \
--providers 10,11
# With email verification
databar waterfall run email_getter \
--params '{"linkedin_url": "https://linkedin.com/in/alice"}' \
--email-verifier 99
```
```bash Bulk run from CSV theme={null}
databar waterfall bulk email_getter --input leads.csv
databar waterfall bulk email_getter --input leads.csv --out results.csv
```
***
## Tables
```bash List and create tables theme={null}
databar table list
databar table list --format json
# Create empty table
databar table create --name "My Leads"
# Create with predefined columns
databar table create --name "My Leads" --columns "email,name,company,linkedin_url"
```
```bash Inspect a table theme={null}
# List columns
databar table columns
databar table columns --format json
# Get rows
databar table rows
databar table rows --page 2 --per-page 500
databar table rows --format csv --out rows.csv
```
```bash Insert rows theme={null}
# From inline JSON array
databar table insert \
--data '[{"email":"alice@example.com","name":"Alice"}]'
# From CSV file
databar table insert --input data.csv
# Auto-create unknown columns
databar table insert --input data.csv --allow-new-columns
# With deduplication
databar table insert --input data.csv --dedupe-keys email
# Multiple dedupe keys
databar table insert --input data.csv --dedupe-keys "email,linkedin_url"
```
```bash Update rows theme={null}
# Rows must include an "id" field (the row UUID)
databar table patch \
--data '[{"id":"row-uuid","name":"Updated Name"}]'
# From CSV (must have "id" column)
databar table patch --input updates.csv
# Only fill empty cells (don't overwrite existing values)
databar table patch --input updates.csv --no-overwrite
```
```bash Upsert rows theme={null}
# Insert or update matched by key column
databar table upsert --key-col email \
--data '[{"email":"alice@example.com","name":"Alice"}]'
# From CSV
databar table upsert --key-col email --input data.csv
```
```bash Table enrichments theme={null}
# List enrichments configured on a table
databar table enrichments
# Add an enrichment to a table
databar table add-enrichment \
--enrichment-id 123 \
--mapping '{"email": "email_column"}'
# Run an enrichment on all table rows
databar table run-enrichment --enrichment-id
# Run only on empty rows
databar table run-enrichment --enrichment-id --run-strategy empty_only
```
***
## Tasks
For long-running operations, tasks can be checked manually or polled until completion:
```bash Check task status theme={null}
databar task get
databar task get --format json
```
```bash Poll until complete theme={null}
# Blocks until the task finishes or times out (~5 minutes)
databar task get --poll
databar task get --poll --format json
```
***
## AI agent usage
The CLI is designed to be invoked by AI agents (Claude Code, Cursor, etc.) with `--format json` for machine-readable output:
```bash theme={null}
# Self-discovery — agent finds the right enrichment
databar enrich list --format json | jq '.[] | select(.name | test("linkedin"; "i"))'
# Get parameters for an enrichment
databar enrich get 123 --format json
# Run and get structured result
databar enrich run 123 --params '{"email": "alice@example.com"}' --format json
# Full table pipeline
databar table rows --format json | jq '.[].email'
```
Exit codes follow Unix conventions — `0` on success, non-zero on error. Errors are written to stderr; data is written to stdout, so piping always works cleanly.
***
## Environment variables
| Variable | Description |
| ----------------- | -------------------------------------------------------------- |
| `DATABAR_API_KEY` | Your Databar API key. Takes priority over `~/.databar/config`. |
***
## Source code
The CLI is open source. View source, report issues, and contribute on GitHub.
# Build with Databar
Source: https://docs.databar.ai/developer-guides
Enrich, transform, and manage your data programmatically with the Databar API, SDK, CLI, or MCP server.
Databar gives you programmatic access to 160+ integrations, enrichment workflows, waterfall logic, and structured tables. Use the REST API, Python SDK, CLI, or MCP server to build data pipelines, enrich your CRM, score leads, or let AI agents handle research for you.
## Get started
Pick the path that fits your stack. Each guide walks you through authentication and your first successful request.
Raw HTTP with cURL, JavaScript, or any language. Start here if you want full control.
Typed client with built-in polling and error handling. Install with `pip install databar`.
Run enrichments and manage tables from your terminal. Great for scripting and AI agents.
Connect Databar to Claude, Cursor, or other MCP-compatible AI tools. No code required.
## Core concepts
**Enrichments** are the building blocks. Each enrichment connects to a data provider (LinkedIn, Clearbit, Hunter, etc.) and returns structured data for a given input. You can run enrichments individually, in bulk, or attach them to a table. [Browse enrichments](/api-reference/endpoint/enrichments-list)
**Waterfalls** chain multiple providers together for the same lookup. If the first provider returns no result, the next one is tried automatically. This maximizes coverage without writing fallback logic yourself. [Browse waterfalls](/api-reference/endpoint/waterfalls-list)
**Tables** are structured datasets that live in your Databar workspace. You create a table, insert rows, attach enrichments or waterfalls, and run them across all rows. Results are stored in the table and accessible via the API or the Databar UI. [Tables API](/api-reference/endpoint/tables-create)
**Connectors** let you bring your own API credentials for supported providers, or define custom HTTP endpoints that Databar can call as enrichment sources. [Connectors API](/api-reference/endpoint/connectors-list)
**Exporters** push data from your tables into external destinations like HubSpot, Salesforce, Google Sheets, or custom webhooks. [Browse exporters](/api-reference/endpoint/exporters-list)
**Tasks** represent async operations. When you run an enrichment or waterfall, you get back a `task_id`. Poll the task endpoint to check status and retrieve results. Task data is stored for 24 hours. [Tasks API](/api-reference/endpoint/tasks-get-status)
## What you can build
* **Lead enrichment pipelines** that pull company data, emails, and phone numbers for every new signup or CRM import. [Walkthrough](/guides/enrich-leads)
* **Waterfall email finders** that try multiple providers until they find a verified email. [Walkthrough](/guides/waterfall-email-finder)
* **Table-driven enrichment workflows** where you create a table, add rows, attach enrichments, and run everything in a few API calls. [Walkthrough](/guides/table-enrichment-pipeline)
* **AI-powered research agents** that use the MCP server to discover and run enrichments with natural language. [MCP quickstart](/quickstart-mcp)
## Explore
All endpoints with request and response examples.
Connect Databar to Claude, Cursor, and other AI tools.
Learn how Databar works from the UI perspective.
# Enrich a list of leads
Source: https://docs.databar.ai/guides/enrich-leads
Pull company data, emails, and phone numbers for a batch of leads using the Databar API.
This walkthrough shows how to take a list of leads (names + companies) and enrich them with contact information using the Databar API.
## What you will do
1. Search for an enrichment that finds emails by name and company
2. Run it in bulk for your entire list
3. Poll for results
## Prerequisites
* A Databar API key ([get one here](https://databar.ai))
* A list of leads with at least a name and company
## Step 1: Find the right enrichment
Search for enrichments that match your use case:
```bash theme={null}
curl "https://api.databar.ai/v1/enrichments/?q=email%20finder" \
-H "x-apikey: YOUR_API_KEY"
```
Look through the results for an enrichment that accepts `name` and `company` (or similar) as input parameters. Note the `id` and check the `price` field.
Use [Get enrichment details](/api-reference/endpoint/enrichments-get) to see all required and optional parameters before running.
## Step 2: Run in bulk
Once you have the enrichment ID, run it against your full list:
```bash theme={null}
curl -X POST "https://api.databar.ai/v1/enrichments/ENRICHMENT_ID/bulk-run" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"params": [
{"full_name": "Sarah Chen", "company": "Stripe"},
{"full_name": "James Lee", "company": "Notion"},
{"full_name": "Maria Garcia", "company": "Figma"}
]
}'
```
You will receive a `task_id` in the response.
## Step 3: Poll for results
Check the task status until it completes:
```bash theme={null}
curl "https://api.databar.ai/v1/tasks/YOUR_TASK_ID" \
-H "x-apikey: YOUR_API_KEY"
```
When `status` is `completed`, the `data` field contains your enriched results with emails, phone numbers, LinkedIn profiles, and other fields depending on the provider.
Task data is stored for **24 hours**. Make sure to retrieve and save your results before they expire.
## With the Python SDK
The SDK handles polling automatically:
```python theme={null}
from databar import DatabarClient
client = DatabarClient()
leads = [
{"full_name": "Sarah Chen", "company": "Stripe"},
{"full_name": "James Lee", "company": "Notion"},
{"full_name": "Maria Garcia", "company": "Figma"},
]
results = client.run_enrichment_bulk_sync(ENRICHMENT_ID, leads)
# Results are aligned to inputs: one element per lead, in the same order, with
# None for leads that returned no data (len(results) == len(leads)).
for lead, result in zip(leads, results):
print(lead["full_name"], "->", result)
```
## Next steps
Maximize email coverage by trying multiple providers.
Store and enrich data in a Databar table for ongoing workflows.
# Table enrichment pipeline
Source: https://docs.databar.ai/guides/table-enrichment-pipeline
Create a table, add rows, attach an enrichment, and run it across all rows with a few API calls.
Tables let you store structured data in Databar and run enrichments across all rows without managing individual API calls. This is the best approach when you want persistent, viewable results that you can also access in the Databar UI.
## What you will do
1. Create a table with columns
2. Insert rows
3. Find and attach an enrichment
4. Run the enrichment on all rows
5. View results in the API or UI
## Prerequisites
* A Databar API key ([get one here](https://databar.ai))
* A dataset (names, emails, domains, etc.)
## Step 1: Create a table
```bash theme={null}
curl -X POST "https://api.databar.ai/v1/table/create" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Lead Enrichment",
"columns": ["name", "company", "domain"]
}'
```
Save the `uuid` from the response. You will use it in every subsequent call.
## Step 2: Insert rows
```bash theme={null}
curl -X POST "https://api.databar.ai/v1/table/TABLE_UUID/rows" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"rows": [
{"fields": {"name": "Sarah Chen", "company": "Stripe", "domain": "stripe.com"}},
{"fields": {"name": "James Lee", "company": "Notion", "domain": "notion.so"}},
{"fields": {"name": "Maria Garcia", "company": "Figma", "domain": "figma.com"}}
]
}'
```
You can insert up to 100 rows per request.
## Step 3: Find and attach an enrichment
First, find the enrichment you want:
```bash theme={null}
curl "https://api.databar.ai/v1/enrichments/?q=company%20data" \
-H "x-apikey: YOUR_API_KEY"
```
Then attach it to the table with a column mapping that tells Databar which columns to use as input:
```bash theme={null}
curl -X POST "https://api.databar.ai/v1/table/TABLE_UUID/add-enrichment" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enrichment": ENRICHMENT_ID,
"mapping": {
"domain": {
"value": "domain",
"type": "mapping"
}
}
}'
```
Each mapping key is an enrichment parameter slug. Set `type` to `"mapping"` to pull the value from a table column (use the column name or UUID as the `value`), or `"simple"` to pass a static value to every row. Save the returned `id` - this is the table-enrichment ID you will use to run it.
## Step 4: Run the enrichment
```bash theme={null}
curl -X POST "https://api.databar.ai/v1/table/TABLE_UUID/run-enrichment/TABLE_ENRICHMENT_ID" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
```
This runs the enrichment on all rows. Use `"run_strategy": "run_empty"` to only process rows that have not been enriched yet.
## Step 5: View results
Fetch the enriched rows:
```bash theme={null}
curl "https://api.databar.ai/v1/table/TABLE_UUID/rows" \
-H "x-apikey: YOUR_API_KEY"
```
Or open the table directly in the Databar UI at `https://databar.ai/table/TABLE_UUID`.
## With the Python SDK
```python theme={null}
from databar import DatabarClient
client = DatabarClient()
# Create table and add rows
table = client.create_table(name="Lead Enrichment", columns=["name", "company", "domain"])
client.create_rows(table.uuid, [
{"name": "Sarah Chen", "company": "Stripe", "domain": "stripe.com"},
{"name": "James Lee", "company": "Notion", "domain": "notion.so"},
{"name": "Maria Garcia", "company": "Figma", "domain": "figma.com"},
])
# Attach and run enrichment
te = client.add_enrichment(table.uuid, ENRICHMENT_ID, mapping={
"domain": {"value": "domain", "type": "mapping"}
})
client.run_table_enrichment(table.uuid, te.id)
# Fetch results
rows = client.get_table_rows(table.uuid)
for row in rows:
print(row)
```
## Next steps
Run a quick headless enrichment without creating a table.
Maximize email coverage by trying multiple providers.
# Waterfall email finder
Source: https://docs.databar.ai/guides/waterfall-email-finder
Find verified emails by trying multiple data providers in sequence with automatic fallback.
A waterfall tries multiple data providers one after another until one returns a result. This is the best way to maximize email coverage without writing fallback logic yourself.
## What you will do
1. Search for a waterfall that finds emails
2. Run it for a single contact
3. Run it in bulk for a list
## Prerequisites
* A Databar API key ([get one here](https://databar.ai))
* A name and company (or domain) for the person you want to find
## Step 1: Find a waterfall
Search available waterfalls:
```bash theme={null}
curl "https://api.databar.ai/v1/waterfalls/?q=email" \
-H "x-apikey: YOUR_API_KEY"
```
Each waterfall lists the providers it uses and the input parameters it expects. Pick the one that matches your data.
## Step 2: Run for a single contact
```bash theme={null}
curl -X POST "https://api.databar.ai/v1/waterfalls/WATERFALL_ID/run" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"params": {
"full_name": "John Smith",
"company": "Google"
}
}'
```
You will receive a `task_id`. Poll it to get results:
```bash theme={null}
curl "https://api.databar.ai/v1/tasks/YOUR_TASK_ID" \
-H "x-apikey: YOUR_API_KEY"
```
The response includes which provider returned the result and whether the email was verified.
## Step 3: Run in bulk
For multiple contacts, use the bulk endpoint:
```bash theme={null}
curl -X POST "https://api.databar.ai/v1/waterfalls/WATERFALL_ID/bulk-run" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"params": [
{"full_name": "Sarah Chen", "company": "Stripe"},
{"full_name": "James Lee", "company": "Notion"}
]
}'
```
Task data is stored for **24 hours**. Make sure to retrieve and save your results before they expire.
## With the Python SDK
```python theme={null}
from databar import DatabarClient
client = DatabarClient()
result = client.run_waterfall_sync(WATERFALL_ID, {
"full_name": "John Smith",
"company": "Google"
})
print(result)
# Bulk
people = [
{"full_name": "Sarah Chen", "company": "Stripe"},
{"full_name": "James Lee", "company": "Notion"},
]
results = client.run_waterfall_bulk_sync(WATERFALL_ID, people)
# Results are aligned to inputs: one element per person, in the same order, with
# None for people that returned no data (len(results) == len(people)).
for person, result in zip(people, results):
print(person["full_name"], "->", result)
```
## Next steps
Enrich a batch of leads with company and contact data.
Store data in a table and run enrichments across all rows.
# Configuration
Source: https://docs.databar.ai/mcp-configuration
Environment variables, safe mode, caching, and task data retention for the Databar MCP server
## Environment variables
These settings apply only when you run the **local** npm or source-built server. The **hosted** server at `https://mcp.databar.ai/mcp` uses your Bearer token only; you cannot set these via env on the remote endpoint (defaults are managed by Databar).
| Variable | Default | Description |
| ------------------------------ | --------------------------- | ------------------------------------------------------------ |
| `DATABAR_API_KEY` | *(required)* | Your Databar API key |
| `DATABAR_BASE_URL` | `https://api.databar.ai/v1` | API base URL |
| `CACHE_TTL_HOURS` | `24` | How long to cache results |
| `MAX_POLL_ATTEMPTS` | `150` | Max polling attempts for async tasks |
| `POLL_INTERVAL_MS` | `2000` | Polling interval in milliseconds |
| `DATABAR_SAFE_MODE` | `true` | Check credit balance before each enrichment |
| `DATABAR_MAX_COST_PER_REQUEST` | *(unset)* | Max estimated credits per request; set to enforce a hard cap |
| `DATABAR_MIN_BALANCE` | `1` | Minimum balance threshold before blocking |
| `DATABAR_AUDIT_LOG` | *(none)* | File path to write audit logs |
| `DATABAR_MAX_RESULT_LENGTH` | `50000` | Truncate results longer than this |
## Safe mode vs unsafe mode
By default, the server runs in **safe mode** — it checks your credit balance before each enrichment to prevent accidental overspending. Even in safe mode, the `DATABAR_MAX_COST_PER_REQUEST` cap is enforced if set.
If you find balance checks slow down bulk operations, you can disable safe mode:
```json theme={null}
{
"env": {
"DATABAR_API_KEY": "your-key",
"DATABAR_SAFE_MODE": "false"
}
}
```
In unsafe mode, the server skips balance checks. You'll see a warning at startup and before bulk operations, but spending will not be blocked. The `DATABAR_MAX_COST_PER_REQUEST` cap is still enforced.
## Caching
Results are cached for **24 hours** by default (controlled by `CACHE_TTL_HOURS` on local installs). Cached lookups don't consume credits.
To force a fresh lookup, pass `skip_cache: true` when calling `run_enrichment`.
## Task data retention
Task data is stored for **24 hours** after completion. If you need the results later, make sure to retrieve them promptly. After 24 hours, task data is permanently deleted and the status will return `gone`.
# MCP Server
Source: https://docs.databar.ai/mcp-server
Connect AI assistants like Claude to Databar's enrichment API
The Databar MCP Server implements the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude, Cursor, Codex, Gemini CLI, and others to interact with Databar's API using natural language.
Instead of writing API calls manually, you can say *"find the email for John Smith at Google"* and your AI assistant will automatically discover the right enrichment, run it, and return the results.
**Use the [hosted MCP server](https://mcp.databar.ai/mcp)** (`https://mcp.databar.ai/mcp`). We ship new tools, fixes, and API alignment there first, so your client always talks to the current implementation without installing or upgrading anything locally.
## Quick start
The MCP server URL for all clients:
```
https://mcp.databar.ai/mcp
```
The recommended way to connect Claude is through the built-in Connectors UI. This uses OAuth so you never need to copy an API key.
Open Claude (web or desktop) and go to **Settings > Connectors**. Scroll to the bottom and click **Add custom connector**.
* **Name:** `Databar`
* **Remote MCP Server URL:** `https://mcp.databar.ai/mcp`
* Leave **Advanced settings** blank.
* Click **Add**.
Claude will redirect you to Databar to authenticate. Click **Authorize** to grant access to your workspace, then you will be redirected back to Claude.
Ask Claude: *"What can the Databar MCP do?"*
If you prefer to authenticate with an API key instead of OAuth, add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json theme={null}
{
"mcpServers": {
"databar": {
"type": "http",
"url": "https://mcp.databar.ai/mcp",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}
```
Restart Claude after saving.
Open `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally) and add:
```json theme={null}
{
"mcpServers": {
"databar": {
"url": "https://mcp.databar.ai/mcp",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}
```
To find your API key, log in to your [Databar workspace](https://databar.ai) and navigate to **Integrations**.
Restart Cursor, then try: *"What can the Databar MCP do?"*
The hosted server supports both **Streamable HTTP** (`POST/GET/DELETE /mcp`) for modern clients and **Legacy SSE** (`GET /sse`) for older clients.
The [`databar-mcp-server`](https://www.npmjs.com/package/databar-mcp-server) **npm package often lags behind the hosted server**. Prefer **Hosted (recommended)** unless you need a **stdio**-based setup (some clients only support spawning a local process), a **custom** `DATABAR_BASE_URL`, or **environment tuning** (see [Configuration](/mcp-configuration)).
**npm / npx**
```bash theme={null}
npm install -g databar-mcp-server
```
Or:
```bash theme={null}
npx databar-mcp-server
```
Example **Claude Desktop** config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json theme={null}
{
"mcpServers": {
"databar": {
"command": "npx",
"args": ["-y", "databar-mcp-server"],
"env": {
"DATABAR_API_KEY": "your-api-key-here"
}
}
}
}
```
**From source** (contributors or pinning a specific commit):
```bash theme={null}
git clone https://github.com/databar-ai/databar-mcp-server.git
cd databar-mcp-server
npm install && npm run build
```
```json theme={null}
{
"mcpServers": {
"databar": {
"command": "node",
"args": ["/path/to/databar-mcp-server/dist/index.js"],
"env": {
"DATABAR_API_KEY": "your-api-key-here"
}
}
}
}
```
## What you can do
The hosted server exposes a large set of tools aligned with the public Databar REST API. The list below reflects the current surface area (tool names and behavior may expand as we deploy updates to the hosted endpoint):
Search, inspect, run enrichments — single or bulk. Remote param choices and pagination-aware runs.
Search and run headless waterfalls; add table waterfalls and run them with enrichments.
Create, rename, or delete tables; add, rename, or delete columns; configure enrichments and exporters on a table.
Insert, patch, upsert, delete, and filter rows; create and manage folders; move tables between folders.
Search exporters, inspect details, attach to tables, list configured exporters, and trigger runs.
Check credit balance and spending-related guardrails (safe mode, per-request cost caps).
Full list of all MCP tools with descriptions.
Environment variables, safe mode, caching, and task expiry.
## Example prompts
Here are some things you can ask your AI assistant once the MCP server is connected:
* *"Get me David Abaev's LinkedIn profile"*
* *"Verify the email [david@databar.ai](mailto:david@databar.ai)"*
* *"Find the email for John Smith at Google using a waterfall"*
* *"Enrich these 10 domains with company data"*
* *"List my tables and show the columns for the first one"*
* *"Create a table called Leads with columns name, email, company and add 5 empty rows"*
* *"Get rows from my Leads table where company contains 'tech'"*
* *"How many credits do I have left?"*
## Links
Recommended — always up to date
Source, issues, and contributions
Local / stdio installs only — may lag hosted
# Bulk Enrichment
Source: https://docs.databar.ai/mcp-skill-bulk
Enrich a list of up to 100 records in a single operation with inline results
## `databar-bulk-enrichment`
**Triggers when** the user provides a list of items to enrich and wants quick inline results without creating a table.
### Workflow
1. Parse the user's list (CSV, JSON, or plain text)
2. `search_enrichments` to find the right provider
3. Estimate cost: `item_count x price_per_enrichment`
4. Confirm with the user
5. `run_bulk_enrichment` (max 100 items per request)
6. Poll `get_task_status`. Results are aligned to inputs: one element per input, in the same order, with `null` for inputs that returned no data (`len(data)` == item count). Join each result back to its input by position.
7. Format results as a markdown table
### Example prompt
*"Verify these emails: [alice@google.com](mailto:alice@google.com), [bob@fake.xyz](mailto:bob@fake.xyz), [carol@stripe.com](mailto:carol@stripe.com)"*
Bulk enrichment supports up to 100 items per request. For larger datasets, the agent will suggest using the [table-driven approach](/mcp-skill-table) instead.
# Single Enrichment
Source: https://docs.databar.ai/mcp-skill-enrichment
Look up a person, company, email, or phone number using the best matching enrichment
## `databar-enrichment`
**Triggers when** the user asks to look up, find, or enrich a single data point — a person, company, email, phone number, or domain.
### Workflow
1. Extract the user's intent and entity type
2. `search_enrichments` to find the right provider
3. `get_enrichment_details` to check parameters, pricing, and choices for any `select`/`mselect` params
4. If a param has `choices.mode = "remote"`, call `get_param_choices` to browse valid values
5. Confirm cost with the user
6. `run_enrichment` and present results
### Example prompt
*"Get me the LinkedIn profile for Sarah Chen at Stripe"*
# Table-Driven Enrichment
Source: https://docs.databar.ai/mcp-skill-table
Create a table, insert rows, attach an enrichment, run it, and get a shareable link
## `databar-table-enrichment`
**Triggers when** the user wants to enrich a dataset at scale using Databar tables — create a table, add rows, run enrichments, and get a link to view results.
### Workflow
1. Parse the user's data (CSV, JSON, or plain text)
2. `create_table` and `create_rows` (up to 100 per batch)
3. `search_enrichments` to find the right provider
4. `add_table_enrichment` with column mapping
5. `run_table_enrichment` on all rows
6. Provide a link: `https://databar.ai/table/{uuid}`
### Example prompt
*"Here are 30 leads with name and company. Create a table and find their emails."*
# Waterfall Enrichment
Source: https://docs.databar.ai/mcp-skill-waterfall
Try multiple data providers in sequence to maximize success rate
## `databar-waterfall`
**Triggers when** the user wants to maximize success rate by trying multiple providers, or explicitly mentions "waterfall".
### Workflow
1. `search_waterfalls` to find available waterfalls
2. Pick the best match based on the user's goal
3. `run_waterfall` (single) or `run_bulk_waterfall` (multiple inputs)
4. Optionally chain with email verification
### Example prompt
*"Find the email for David Kim at Databar using a waterfall"*
# Agent Skills
Source: https://docs.databar.ai/mcp-skills
Pre-built workflow skills that teach AI agents how to use Databar
The MCP server ships with **Agent Skills** — pre-built workflow instructions that teach AI agents how to combine Databar tools for common tasks.
Skills follow the open [SKILL.md](https://agentskills.io/) standard and work across **27+ agents** including Claude, Cursor, Codex, Gemini CLI, OpenClaw, Windsurf, and GitHub Copilot.
Skills work with the [hosted MCP server](https://mcp.databar.ai/mcp) (recommended). They also work with a **local** server via npm or a source build; the **npm package may lag behind hosted**, so prefer the remote URL when your client supports it.
## Available skills
Look up a person, company, email, or phone number using the best matching enrichment.
Create a table, insert rows, attach an enrichment, run it, and get a shareable link.
Try multiple data providers in sequence to maximize success rate.
Enrich a list of up to 100 records in a single operation with inline results.
## How skills work
Without skills, you have to guide the AI step-by-step: "search for an enrichment, then get details, then run it..." With skills, you just say **"find the email for John Smith at Google"** and the agent knows the full workflow automatically.
Skills use a three-phase loading model to stay efficient:
| Phase | What loads | Token cost |
| -------------- | --------------------------------------- | ------------------------ |
| **Discovery** | Name and description only | \~100 tokens per skill |
| **Activation** | Full instructions when the task matches | Under 5,000 tokens |
| **Execution** | Agent follows the workflow | Zero additional overhead |
Skills are loaded on demand — they don't consume context until the agent decides they're relevant to your request.
## Installing skills
Skills are included in the `skills/` folder of the [GitHub repo](https://github.com/databar-ai/databar-mcp-server). To use them:
Copy the skill folders into your Claude skills directory:
```bash theme={null}
git clone https://github.com/databar-ai/databar-mcp-server.git
cp -r databar-mcp-server/skills/* ~/.claude/skills/
```
Claude will automatically discover and activate the skills when relevant.
Copy the skill folders into your project's `.claude/skills/` directory (most agents that support SKILL.md use this path):
```bash theme={null}
git clone https://github.com/databar-ai/databar-mcp-server.git
mkdir -p .claude/skills
cp -r databar-mcp-server/skills/* .claude/skills/
```
Copy to your OpenClaw skills directory:
```bash theme={null}
git clone https://github.com/databar-ai/databar-mcp-server.git
cp -r databar-mcp-server/skills/* ~/.openclaw/skills/
```
# Available Tools
Source: https://docs.databar.ai/mcp-tools
Complete list of MCP tools exposed by the Databar MCP server
The Databar MCP server exposes the following tools. All tools are available on the [hosted server](https://mcp.databar.ai/mcp) and the local npm/source installs.
Tool names and behavior may expand as we deploy updates to the hosted endpoint. The list below reflects the current surface area.
## Enrichments
| Tool | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| `search_enrichments` | Search enrichments by keyword or category (BYOK providers you have not connected are excluded) |
| `get_enrichment_details` | Parameters, pricing, response fields, and inline or remote choice metadata |
| `get_param_choices` | Paginated, searchable choices for remote `select` / `mselect` params |
| `run_enrichment` | Run one enrichment with polling, caching, optional `pages` for paginated enrichments |
| `run_bulk_enrichment` | Bulk run with optional `pages` per record for paginated enrichments |
## Waterfalls
| Tool | Description |
| ---------------------- | ------------------------------------------------------------------- |
| `search_waterfalls` | Search waterfall definitions |
| `run_waterfall` | Run a headless waterfall (optional provider IDs, email verifier) |
| `run_bulk_waterfall` | Bulk headless waterfall runs |
| `add_table_waterfall` | Attach a waterfall to a table with provider list and column mapping |
| `get_table_waterfalls` | List all waterfalls installed on a table |
## Tables
| Tool | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `create_table` | Create a table (optional name, columns, empty row count) |
| `list_tables` | List tables (UUID, name, timestamps) |
| `rename_table` | Rename a table |
| `delete_table` | Permanently delete a table |
| `get_table_columns` | Column schema (names, types, internal names) |
| `create_column` | Add a column |
| `rename_column` | Rename a column by ID |
| `delete_column` | Delete a column by ID |
| `get_table_rows` | Paginated rows with structured filters (`equals`, `contains`, etc.) |
| `get_table_enrichments` | List all enrichments configured on a table |
| `add_table_enrichment` | Map enrichment params to columns or static values (supports `{column}` placeholders) |
| `run_table_enrichment` | Run a table enrichment or table waterfall (`run_all` / `run_empty` / `run_errors`, optional `row_ids`) |
## Row operations
| Tool | Description |
| ------------- | -------------------------------------------------------------------------- |
| `create_rows` | Insert up to 100 rows per request; optional `allow_new_columns` and dedupe |
| `patch_rows` | Patch up to 100 rows by ID |
| `upsert_rows` | Upsert up to 100 rows by match key |
| `delete_rows` | Delete rows by ID list |
## Exporters
| Tool | Description |
| ---------------------- | -------------------------------------------------------------------------- |
| `search_exporters` | Discover CRM / destination exporters |
| `get_exporter_details` | Exporter parameters and fields |
| `add_table_exporter` | Attach an exporter with mapping (optional OAuth key, custom body template) |
| `get_table_exporters` | List all exporters configured on a table |
| `run_table_exporter` | Trigger an exporter run (`run_all` / `run_empty` / `run_errors`) |
## Folders
| Tool | Description |
| ---------------------- | ---------------------------------------------------------- |
| `create_folder` | Create a folder |
| `list_folders` | List folders |
| `rename_folder` | Rename a folder |
| `delete_folder` | Delete a folder (tables inside are not deleted) |
| `move_table_to_folder` | Move a table into a folder or `null` to remove from folder |
## Account
| Tool | Description |
| ------------------ | ------------------------------- |
| `get_user_balance` | Credit balance and account info |
Many tools that run enrichments, waterfalls, or exporters are subject to [spending guardrails](/mcp-configuration#safe-mode-vs-unsafe-mode) (safe mode, per-request cost caps, minimum balance thresholds).
# AI prompts
Source: https://docs.databar.ai/product-guide/ai-prompts
Generate and reuse AI prompt templates across your workspace.
AI prompts let you run custom instructions against your table data, either as standalone enrichments or as the driving logic behind the [AI Researcher](/product-guide/ai-researcher). Databar provides tools to write prompts manually, generate them automatically, and save them as reusable templates for your entire workspace.
## AI Prompt enrichments
An AI Prompt enrichment runs a custom prompt on every row in your table. Reference column values using the `{` syntax so the prompt adapts to each row's data.
**Example:** You have a table of company names and descriptions. Add an AI Prompt enrichment with the instruction:
```
Classify {Company Description} into one of: SaaS, Marketplace, Hardware, Services.
```
For each row, the AI reads the description and writes the classification into a new column.
Click **Enrich** in the table toolbar and search for **AI Prompt**.
Enter your instruction in the prompt editor. Use `{` to insert column references wherever you need row-specific data.
Select which response fields to add to your table.
Click **Run** to process rows. Start with a single row to validate the output.
## AI Prompt Generator
Not sure how to phrase your prompt? Describe what you want in plain English and Databar will generate a well-structured prompt for you. The generator works for both AI Prompt enrichments and [AI Researcher](/product-guide/ai-researcher) agents.
In the prompt editor, click **Generate prompt**.
Write a short description of what you want the AI to do. For example, "Summarize each company's value proposition in one sentence."
The generator produces a prompt with proper structure and column references. Edit it further if needed, then apply it to your enrichment.
The prompt generator is especially helpful when you need structured output formats (lists, JSON, specific fields). It handles the formatting instructions for you.
## AI Prompt Templates
Save any prompt as a **workspace-wide template** so you and your team can reuse it across tables without rewriting it each time. Templates are ideal for prompts you run regularly: lead qualification, content classification, data extraction patterns, and more.
### Saving a template
After writing or generating a prompt, click **Save as template**, give it a name, and it becomes available across your entire workspace.
### Using a template
When setting up an AI Prompt enrichment or AI Researcher, click **Templates** to browse your saved prompts. Select one, and the prompt editor is pre-filled with the template content. Adjust column references as needed for the current table.
## Required vs. optional column references
When your prompt includes column references, each reference can be toggled between **required** and **optional**:
| Setting | Behavior |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| **Required** | If the referenced column is empty for a row, the enrichment skips that row. No credits are consumed. |
| **Optional** | The enrichment runs even if the value is empty. The AI receives a blank value for that reference. |
Use the toggle next to each column reference in the prompt editor to set its requirement level.
Leaving all references as optional may cause the AI to produce low-quality or irrelevant outputs when key data is missing. Mark the columns that are essential to your prompt as required.
## Next steps
Use AI agents to visit websites and extract structured data.
Learn how to add and manage enrichments on your tables.
Understand how AI prompt runs are billed.
# AI Researcher
Source: https://docs.databar.ai/product-guide/ai-researcher
Use AI agents to research and enrich your data from across the web.
The AI Researcher is an AI-powered enrichment that can visit websites, extract information, and return structured data based on your prompt. Give it a list of URLs from your table and a natural-language instruction, and it will browse each site, pull out the data you asked for, and write the results back into your table.
## How it works
The AI Researcher takes two inputs:
1. **A prompt**: a natural-language description of what you want to extract (e.g., "Find the pricing model and list each tier").
2. **A column of URLs**: the websites the agent should visit.
For each row, the agent opens the linked page, reads its content, and returns a structured response based on your prompt. Unlike single-page scrapers, the AI Researcher can follow internal links and synthesize information across multiple pages on the same site.
## Example use cases
| Input column | Prompt | Output |
| ---------------------- | --------------------------------------- | ---------------------------------------------------------- |
| Company websites | "Get their pricing model" | Pricing tiers, free-trial availability, enterprise options |
| LinkedIn company pages | "Find the CEO" | CEO name, role, and profile link |
| Startup websites | "Check if they recently raised funding" | Yes/no flag with round size, date, and investors |
| Product pages | "Summarize the key features" | Bulleted feature list per product |
## Setting up an AI Researcher enrichment
Click **Enrich** in the table toolbar, then search for **AI Researcher** in the enrichment catalog or click the **AI Researcher** button directly.
Describe what you want the agent to extract. Be specific. The clearer the prompt, the better the output. You can reference column values using the `{` syntax to make prompts dynamic per row.
Choose which response fields to add as columns in your table. You can optionally remove the **result** and **reasoning** fields if you only need the extracted data.
Hit **Run** to process your rows. Start with a single row to verify the output before running the full table.
## Customizable outputs
By default, the AI Researcher returns a **result** field and a **reasoning** field that explains how the agent arrived at its answer. Both fields are now fully optional. Remove either one during setup if you only need the raw extracted data.
## Required column references
When your prompt references columns with the `{` syntax, you can mark each reference as **required** or **optional**. If a required column value is empty for a given row, the enrichment skips that row entirely. This prevents unnecessary executions and avoids sending incomplete inputs to the AI model.
Marking references as required is especially useful when running the AI Researcher on large tables where some rows may have missing URLs or context fields.
## AI models
Databar uses the latest AI models to power the AI Researcher, ensuring high-quality extraction and reliable structured outputs. Model updates are applied automatically. No configuration needed on your end.
## Tips for better results
* **Be specific in your prompt.** Instead of "Get info about the company," try "Extract the founding year, headquarters city, and number of employees."
* **Test on a single row first.** Verify the output format before committing to a full run.
* **Use the AI Prompt Generator.** Describe what you want in plain English and let Databar generate a well-structured prompt for you. See [AI prompts](/product-guide/ai-prompts).
* **Combine with other enrichments.** Use the AI Researcher to extract URLs or identifiers, then chain additional enrichments for deeper data.
## FAQ
No, AI Researcher currently runs on Databar's managed AI infrastructure. You cannot bring your own API key. However, AI Researcher is priced very competitively, so the cost per run is kept low.
Yes. You can choose which response fields to include as columns during setup. The default **result** and **reasoning** fields are both optional, so you can remove either one if you only need the raw extracted data. You can also shape the output format through your prompt (e.g., asking for JSON, bullet points, or specific fields).
## Next steps
Generate, save, and reuse prompt templates across your workspace.
Learn how enrichments work and how to manage them.
Understand how tables, columns, and rows fit together.
See how AI Researcher runs are billed.
# Authorization & API keys
Source: https://docs.databar.ai/product-guide/authorization
How authentication works for data providers on Databar.
Every data provider on Databar uses one of four authorization methods. The method determines whether you need to supply your own API key, whether Databar handles authentication for you, or whether no authentication is needed at all.
## No authorization required (No Auth)
Some providers offer publicly accessible endpoints that don't require authentication.
* No API key is needed. Just configure the enrichment and run it.
* These enrichments display a **"No API key required"** badge.
* Each request consumes **0 credits** and **1 action**.
## Authorization required (API key)
For providers that require authentication, you supply your own API key from the provider's website.
Visit the data provider's website and generate or copy your API key from their developer dashboard. When you add a key in Databar, we usually provide instructions on how to find and generate the key for that specific provider.
Click the key icon on the enrichment card, then click **Authorize**. Paste your API key into the field and save.
Once you add a key to a data source, it becomes available across all endpoints from that provider. You don't need to re-enter it for each enrichment.
Each request made with your own API key consumes **0 credits** and **1 action**.
To remove or update a key, go to the **Manage Integrations** page in your workspace settings.
Once you authorize an API (whether via API key, OAuth, or the API Network), that provider becomes available across all of Databar, including the [REST API](/api-reference/introduction), [Python SDK](/python-sdk), [CLI](/cli), and [MCP Server](/mcp-server).
API keys you add to Databar are completely confidential. They are encrypted at rest and never accessed, viewed, or used by the Databar team.
## Authorization via Databar (API Network)
Databar partners with **100+ data providers** to offer keyless access through the API Network. You don't need to sign up with each provider or manage any API keys. Just click **Run** and Databar handles authentication on your behalf.
* No setup needed for supported providers.
* Each request consumes **API Network credits** based on the provider's per-row cost.
* Some providers are only available on paid plans.
Even for providers available through the API Network, you can add your own API key if you prefer to use your own quota or rate limits. Your key takes priority over the API Network connection when both are configured.
## OAuth
Integrations like HubSpot, Salesforce, and Pipedrive use OAuth for authentication. Instead of pasting an API key, you authenticate directly on the provider's website.
Click the **Authorize on \[Provider]** button on the enrichment or exporter card.
You'll be redirected to the provider's login page. Sign in and grant Databar the requested permissions.
After authorizing, you're redirected back to Databar. The connection is now active and ready to use.
Each request made through an OAuth connection consumes **0 credits** and **1 action**.
Databar currently supports one OAuth account per API integration. If you need to switch accounts, disconnect the current one from the Integrations page and re-authorize with a different account.
## Authorization at a glance
| Method | API key needed? | Credit cost | Action cost |
| ------------ | -------------------------- | ----------------- | ----------- |
| No Auth | No | 0 | 1 |
| Your API key | Yes (from provider) | 0 | 1 |
| API Network | No | Per-provider rate | 0 |
| OAuth | No (authorize via browser) | 0 | 1 |
## Setting a default API key
If you have multiple API keys for the same provider (for example, a personal key and a team key), you can set one as the default. The default key is used automatically whenever you run an enrichment with that provider.
Click the arrow next to your workspace name and select **Manage Integrations**.
Find and click on the provider you want to configure.
Click **Add authentication credentials** and enter your API key.
Click the checkbox next to your key to set it as the default. When enabled, this key will be used for all requests to that provider.
## Security
All API keys stored on Databar are encrypted and treated as confidential. The Databar team never accesses, views, or uses your keys. You can delete any stored key at any time from the **My Connections / Integrations** page.
If you have questions about data security, contact [info@databar.ai](mailto:info@databar.ai).
## Next steps
Add your own REST APIs with custom authentication.
Understand how credits and actions are consumed.
Learn how to enrich your tables with third-party data.
# Automations
Source: https://docs.databar.ai/product-guide/automations
Schedule and automate your enrichment runs.
Automations let you run enrichments without manual intervention. Instead of clicking **Run** each time, you configure a trigger (a schedule, a data change, or a manual button) and Databar handles the rest.
## Automation modes
Databar supports three automation strategies. You select one when adding or editing an enrichment under the **Update frequency** section.
The default mode. Nothing runs until you manually click the **Run** button in the table toolbar. Use this when you want full control over when data is processed.
The enrichment runs automatically whenever a source column changes. If a new email is added or an existing domain is modified, the enrichment fires for the affected rows.
This is the best mode for live data flows where new records arrive continuously, whether via API, webhook, or manual entry.
The enrichment runs at a fixed interval. Available frequencies:
| Interval | Use case |
| ------------------------------ | ------------------------- |
| Every minute | Near-real-time monitoring |
| Every 5 / 10 / 15 / 30 minutes | Frequent polling |
| Hourly | Standard tracking cadence |
| Daily | Daily digests and reports |
| Weekly | Low-frequency updates |
| Monthly | Periodic audits |
This is the best mode for trackers and dashboards that need regular refreshes without external triggers.
## Setting up an automation
When you add a new enrichment to your table, the setup wizard includes an **Update frequency** section. Select the mode that fits your workflow:
1. **Run on click**: no additional configuration needed.
2. **Run on update**: select the source columns that should trigger re-enrichment when they change.
3. **Run on schedule**: pick the interval from the dropdown.
You can change the automation mode at any time by editing the enrichment settings.
## Run conditions with automations
[Run conditions](/product-guide/run-conditions) apply to all three automation modes. Even when an enrichment is triggered automatically (by schedule or data change), each row is still evaluated against the condition before it runs. Rows that fail the condition are skipped and do not consume credits.
This lets you combine powerful automations with precise targeting. For example, you can schedule an hourly run but only process rows where `{status} == "active" && {email} != ""`.
## Credit usage
Automated enrichments consume credits on every run, just like manual runs. Make sure your account has sufficient credits before enabling high-frequency schedules. Monitor your balance on the [Credits and billing](/product-guide/credits-and-billing) page.
## Scheduling for data sources (query builder)
If your table is powered by a data source through the query builder, you can schedule the data source itself to refresh on a recurring basis.
### Frequency options
Data source schedules support:
* **Weekly**, **daily**, **hourly**, or **minute intervals**: pick from the dropdown.
* **Cron expressions**: for precise timing (e.g., every weekday at 9 AM UTC).
### Update rules
| Rule | Behavior |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Update dataset** | Replaces the existing rows with the latest results. Use when you want a current snapshot. |
| **Expand dataset** | Appends new rows without removing existing ones. Use when you want to accumulate data over time. |
### Run on launch
Enable **Run on launch** to execute the data source query immediately when the schedule is activated, rather than waiting for the first scheduled interval.
### Dynamic dates
Data source parameters accept dynamic date values:
* `now()`: the current date and time at execution.
* Relative offsets like `-1 day`, `-2 days`, `-3 days`: useful for fetching recent data windows.
This lets you build queries like "fetch all new leads from the last 24 hours" that stay current without manual updates.
You cannot run single ad-hoc queries while a scheduler is active on the same data source. Pause the scheduler first if you need to run a one-off query.
## Next steps
Learn how to add and configure enrichments.
Write conditional expressions to target specific rows.
Monitor credit usage and manage your plan.
# Chrome extension
Source: https://docs.databar.ai/product-guide/chrome-extension
Collect data from any website and send it directly to Databar.
The Databar Chrome Extension lets you collect structured data from any website without writing code. Open the sidebar, click on the elements you want, and export the results as a CSV or send them straight to your Databar workspace.
## How it works
The extension opens as a persistent sidebar pinned to the right side of your browser. It stays visible while you browse, scroll, and interact with the page, giving you a full workspace for selecting and organizing your data.
1. Click on any element on the page to select it
2. The extension automatically detects similar elements across the page
3. Review and refine your selections in the sidebar
4. Export to CSV or send directly to Databar
## Key features
### Link extraction
While in selection mode, press **L** on your keyboard to enable link extraction. The extension will grab both the visible text of the element you select and its underlying hyperlink as a separate column. This is especially useful for collecting directories, search results, or any list where you need both the label and the URL it points to.
### Sub-element extraction
Select a container element (such as a product card or search result) and click the **Layers** button to reveal all extractable sub-elements inside it. Pick specific data points like title, price, rating, or image URL and add them as child fields grouped with their parent container.
### Watch mode
Watch mode monitors the page for new elements and automatically adds them to your dataset as they appear. This is ideal for page-based pagination: click to the next page and Watch mode picks up the new items without you having to re-select anything. It also works when new content loads dynamically on the same page.
### Auto-scroll
Auto-scroll automatically scrolls the page for you, capturing elements as it goes. Combined with Watch mode, this handles infinite-scroll pages end to end: the extension scrolls, detects new elements, and adds them to your list automatically.
### Smart detection
When you select an element, the extension identifies similar elements across the entire page automatically. One click can capture dozens of matching records.
### CSS selector preview
A preview box displays the CSS selector being used for each selected element, giving you visibility into exactly what the extension is targeting.
### Google Sheets import
When you navigate to a Google Sheets page, the extension switches to a dedicated import view. Copy a range of cells (including headers) and import them directly into Databar via the clipboard.
## Getting started
Install the Databar extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/easy-web-scraper-by-datab/diijlidbfjnlccmmalabeflgckicodbj). After installation, click the Databar icon in your browser toolbar to open the sidebar.
Open any webpage that contains the data you want to collect: product listings, search results, directories, or any structured content.
Click **Add Field** in the sidebar, then click on elements on the page to select them. Each selected element becomes a column in your extracted dataset.
For container elements like cards or listings, click the **Layers** button to drill into nested sub-elements. Pick the specific data points you want and add them as child fields.
Download the extracted data as a CSV file, or click the **Databar** button to send it directly to your Databar workspace as a new table.
## Additional details
* **Authentication** is automatic. The extension detects your active Databar session, so no API key entry is needed. API key authentication is available as an alternative in the sidebar settings.
* **CSV file naming** uses a descriptive format: `{Page Title} | {Site Name} | {Date}.csv` for easy identification.
* **Duplicate column handling** automatically renames columns when two selected elements produce the same header (e.g., "Name (2)").
* **Cancel button** lets you exit selection mode at any time without losing your existing selections.
## After extracting
Once your data is in Databar, you can enrich it using any of Databar's [enrichments](/product-guide/enrichments): verify emails, look up company data, find social profiles, and more. The extracted table works exactly like any other Databar table.
## Next steps
Enrich your extracted data with third-party providers
Learn how to work with tables in Databar
# Columns
Source: https://docs.databar.ai/product-guide/columns
Column types, management, and grouping in Databar tables.
Columns define the structure of your table. Each column has a name and a type that determines how its values are stored and displayed. You can add columns manually, or they are created automatically when you attach an enrichment.
## Adding columns
Click the **+** button at the end of the column header row to add a new column. Give it a name and select a type.
Columns created by enrichments are added automatically and named based on the data field they return.
## Managing columns
Click any column header to open the column menu. From here you can:
* **Rename** the column
* **Delete** the column
* **Change the column type**
* **Sort** the table by this column (ascending or descending)
* **Filter** by this column's values
* **Hide** the column (use the toolbar to show hidden columns again)
* **Pin** the column to the left or right side of the table so it stays visible while scrolling horizontally
* **Remove duplicates** based on this column's values (see [Deduplication](/product-guide/deduplication))
* **Download images** as a zip file (Image columns only)
You can also **resize** columns by dragging the edge of any column header, and **reorder** columns by dragging the column header to a new position.
## Column types
Each column has a type that controls how values are stored, validated, and displayed.
Free-form strings. This is the default type for new columns and most enrichment results. Text columns can hold any value including names, emails, descriptions, and identifiers.
Integers and decimal values. Numbers are right-aligned in cells and can be sorted numerically. Use this for quantities, scores, employee counts, and similar numeric data.
Same as Number but formatted with a currency symbol. Use this for revenue, pricing, funding amounts, and other monetary values. The display includes appropriate formatting while the underlying value remains a number.
True/false values displayed as checkboxes. Click the checkbox to toggle the value. Useful for tracking completion, verification status, or any binary state.
Date values with a configurable display format. Databar automatically converts common date formats, including UNIX timestamps, into human-readable dates.
A date paired with a time value. Use this when you need to track both the day and the specific time, such as event timestamps, log entries, or scheduled actions.
Clickable links. Values are rendered as hyperlinks that open in a new tab when clicked. Useful for website URLs, LinkedIn profiles, social links, and any web addresses.
Inline image previews rendered from URLs. When a cell contains an image URL, the table displays a thumbnail preview directly in the cell. Click to view the full image.
Nested objects and arrays displayed with an expandable viewer. Many API providers return structured JSON data. Click a JSON cell to open the expanded viewer for easier navigation of nested structures.
You can use the **JSON Expander** to flatten specific fields from a JSON column into their own top-level columns. See [JSON Expander](/product-guide/json-expander) for details.
A single-value dropdown. Define a set of options and pick one per cell. Useful for categorizing rows with statuses, labels, or stages.
A multi-value dropdown. Select one or more options per cell. Useful for tagging rows with multiple labels, categories, or attributes.
### Changing a column's type
You can change an existing column's type by clicking the column header and selecting a new type. Databar will attempt to coerce existing values to the new type. For example, converting a Text column to Number will parse numeric strings into numbers.
If your column contains values that cannot be converted to the new type, those values may be lost. For example, changing a Text column with non-numeric values to Number will clear any cells that don't contain valid numbers.
## Column grouping
When an enrichment returns multiple fields, those columns are grouped together under a collapsible header. This keeps your table readable even when dozens of data points are attached to each row.
Grouped columns can be collapsed or expanded by clicking the group header. This is especially useful when working with enrichments that return many fields (e.g., company data with name, description, employee count, funding, and more).
### User-created vs. enrichment columns
* **User-created columns** are the columns you add manually. They appear as standalone columns in your table.
* **Enrichment columns** are created automatically when you attach an enrichment. They are grouped under the enrichment name and display cell-level [enrichment statuses](/product-guide/tables-overview#cell-level-enrichment-statuses) (success, no data, error, pending).
Enrichment columns have additional options in their column menu, including a **Settings** shortcut to open the enrichment sidebar and an **Actions** submenu for running the enrichment on all rows, empty rows only, rows with errors, or filtered rows.
## Related
Learn how tables work in Databar
Remove duplicate rows based on column values
Flatten JSON fields into their own columns
Attach data providers to your columns
# Credit usage
Source: https://docs.databar.ai/product-guide/credit-usage
Monitor your workspace's credit spending with usage charts and detailed transaction logs.
The Credit Usage page gives you full visibility into how your workspace is spending credits. You can view historic usage trends, break them down by time period, and inspect every individual transaction.
## Accessing the Credit Usage page
Click the **arrow** next to your workspace name in the top-left corner.
Select **Workspace Settings** from the dropdown.
Click the **Credit Usage** tab in the left sidebar of the settings page.
## Credit usage overview
The top section displays a chart of your credit spending over time. You can customize the view with two controls:
* **Time period** - switch between different ranges (e.g., last 3 months, last 30 days) to zoom in or out on your usage history.
* **Time breakdown** - toggle between **Daily**, **Weekly**, or **Monthly** granularity to see spending patterns at different levels of detail.
The chart also shows the total number of credits consumed in the selected period.
## Detailed logs
Below the chart, the detailed logs section lists every individual credit transaction in your workspace. Each log entry includes:
| Column | Description |
| ----------- | ----------------------------------------------------------------- |
| Date & time | When the request was made |
| Item | The enrichment or API call that was executed |
| Provider | The data source that handled the request |
| Source | The table the request was made from (clickable link to the table) |
| Credits | The number of credits consumed by this request |
Requests that consumed zero credits are also shown in the logs. This gives you full observability into all workspace activity, not just the requests that cost credits.
## Related
Understand how credits and actions work
Get notified when your balance is running low
# Credits & billing
Source: https://docs.databar.ai/product-guide/credits-and-billing
Learn how to manage and spend your data credits on Databar.
Databar has two ways of metering usage: **API Network Credits** and **Actions**. In short, API Network Credits are used to connect to external data providers, while Actions are used for free APIs, requests to custom-added connectors (which you have added via the [Add an API](/product-guide/custom-apis) feature), and API requests using your own API key.
## Credits
To make the experience of using Databar as easy as possible, we partnered with 100+ data providers to offer keyless access to their data. With Databar you can access all APIs and data sources that are part of the API Network without needing an API key or additional forms of authorization.
Credits are **only** consumed when you use Databar's credentials to access a third-party data provider through the API Network. If you bring your own API key or use [Custom Http APIs](/product-guide/custom-apis), no credits are used.
For example, you can use API Network credits to connect to both [BuiltWith](https://databar.ai/explore/builtwith-api) for tech stack data and to [People Data Labs](https://databar.ai/explore/people-data-labs-api) for emails.
### Variable pricing
Each data source prices its data differently, which is why some connectors can cost 4 credits per run and others 20.
For some connectors, the size of the request can also impact the credit pricing. For example, with the Google Maps scraper we charge 0.15 credits per location found. So if you input 100 in the "Number of locations" field, you'll be charged 15 credits for a successful run.
### How credits are billed with enrichments
The cost for enrichments is on a per-row basis:
**Total price = Base cost per row x Number of rows to be enriched**
Before running, the enrichment sidebar shows an expected total price so you can confirm before committing.
### Purchasing additional credits
Each plan on Databar comes with a certain number of API Network credits. However, you can also purchase credits as add-ons from your [workspace settings](/product-guide/workspace-settings).
Credit add-ons are added to your current billing cycle and roll over based on your plan terms (see below).
### Credit rollover
Credits roll over to the next billing cycle, so unused credits are not lost at the end of each month.
* **Annual plans** receive their full 12-month allotment of credits up front. This is a significant benefit, as you have your entire year's credits available from day one to use at your own pace.
* **Monthly plans** roll over unused credits for one additional month. Any credits still unused after that extra month will expire.
## Actions
Actions are meant for usage towards any requests that are not using the Databar API key. Think of an action as similar to a "run" or a "zap" on Zapier. Actions are consumed in the following situations:
* If you make requests to **OAuth connectors** (for example, HubSpot or Salesforce integrations)
* If you make requests to **free APIs**
* If you make requests with **your own API key**
* If you make requests to **custom-added APIs**
Every plan on Databar comes with a very generous number of actions by default. As of 2026, the Scale plan includes unlimited actions. In practice, most users will rarely run into action limits.
Formulas, JSON expander, merge columns, deduplication, and similar in-table transformations do not consume actions or credits. These are free to use regardless of your plan.
## Plans and pricing
Databar offers multiple pricing tiers. All plans include keyless API access through the API Network. The difference is in the number of credits, actions, and features included.
For current pricing details, visit [databar.ai/pricing](https://databar.ai/pricing).
## Low credit alerts
You can set up email notifications that fire when your credit balance drops below a threshold you define. See the dedicated [Low credit alerts](/product-guide/low-credit-alerts) page for setup instructions.
## Related
Configure alerts and purchase credits
Check your credit balance programmatically
# Custom Http APIs
Source: https://docs.databar.ai/product-guide/custom-apis
Add your own REST APIs to Databar for custom enrichments and exports.
Databar's enrichment library covers 160+ integrations, but sometimes you need one that isn't available yet. Custom APIs let you connect any REST endpoint (whether it's a public API, an internal service, or your own CRM) and use it directly inside Databar tables.
## Why add custom APIs
Custom APIs are useful when:
* **The integration you need isn't in Databar's library**: connect any public REST API yourself instead of waiting for official support.
* **You have internal or private APIs**: pull data from internal services that aren't publicly available.
* **You want to connect to your CRM or internal systems**: push enriched data directly to the tools your team already uses.
* **You need custom exporters**: send table data to any endpoint that accepts HTTP requests.
## Two types of custom APIs
Databar supports two categories of custom connectors:
| Type | Direction | Where it appears |
| --------------------- | ------------- | --------------------------------------------------------------- |
| **Custom enrichment** | Pull data in | Under "Add or use your own REST API" in the **Enrich** sidebar |
| **Custom exporter** | Push data out | Under "Send this data to a custom API" in the **Share** sidebar |
## How to add a custom API
Go to your workspace home and click **Integrations**.
Click **Connect a custom API**.
Enter the endpoint URL, select the HTTP method, configure authentication, and define request parameters.
Click **Save**. Your custom API is now available in the enrichment or exporter catalog depending on how you configured it.
For custom enrichments, you'll find it under **Add or use your own REST API** in the Enrich sidebar.
Add the custom API to a table just like any other enrichment or exporter. Map your table columns to the API's request parameters.
Click **Add Columns** (for enrichments) or configure your export, then hit **Run**.
## Supported HTTP methods
Custom APIs support the following HTTP methods:
* **GET**: retrieve data from the endpoint
* **POST**: send data in the request body
* **PATCH**: partially update a resource
* **PUT**: replace a resource entirely
## Advanced settings
### Override content-type parameters
You can override API-specific text, like content-types, by simply adding them as a parameter. For example, if you want to override the `Content-Type` parameter and send:
```json theme={null}
"Content-Type": "application/x-www-form-urlencoded"
```
Then simply add it as a parameter and Databar will override the value that is sent by default.
### Custom body templates
For APIs that require a specific request body structure, click **Use a custom template** under Body parameters. Use dollar signs around parameter names to insert dynamic values from your table columns:
```json theme={null}
{
"contact": {
"email": "$email$",
"name": "$full_name$"
}
}
```
When the enrichment runs, `$email$` and `$full_name$` are replaced with the corresponding column values for each row.
### Rate limit and concurrency controls
Rate limit and concurrency controls are available on Scale+ plans.
Configure the maximum number of requests per second and the number of simultaneous requests for your custom APIs. This lets you fine-tune performance for high-volume runs while staying within the provider's rate limits.
## Plan availability
Custom API access depends on your Databar plan. Check your [workspace settings](/product-guide/workspace-settings) or visit [databar.ai/pricing](https://databar.ai/pricing) for details.
## Next steps
Learn how authentication works for data providers.
See how enrichments work with your tables.
Understand how custom API usage is billed.
# Debug requests
Source: https://docs.databar.ai/product-guide/debug-requests
Understand enrichment statuses and use data logs to troubleshoot errors.
Databar gives you two layers of visibility into what happens when enrichments run: cell-level status indicators directly in your table, and detailed data logs for deeper investigation.
## Cell-level enrichment statuses
Each cell populated by an enrichment displays a status indicator showing what happened during processing. This is the fastest way to spot issues at a glance.
Data was returned and written to the cell. No action needed.
The provider was reached successfully, but returned no matching result for the given input. This is not an error. The provider simply does not have information for that particular query. Try a different provider or verify your input values.
Something went wrong during the request. Hover over the triangle icon in the cell to see a tooltip with the error message and status code. Check the [data logs](#accessing-data-logs) for full details.
The enrichment is still running for this row. Wait for processing to complete.
The row did not satisfy the [run conditions](/product-guide/run-conditions) configured for this enrichment. The enrichment was skipped and no credits were consumed. Review your run condition expression if you expected this row to be processed.
One or more required input columns are empty for this row. The enrichment cannot run without the necessary input values. Fill in the missing data and re-run.
## Accessing data logs
For deeper investigation, each table has a **Data logs** button located at the bottom of the table view, next to the **Add rows** button. Click it to open the log panel for that table.
## Log columns
The data logs panel shows the following information for each request:
| Column | Description |
| ---------------- | ------------------------------------------------------------------------------------- |
| Status | Whether the request completed successfully, returned no data, or failed with an error |
| API / Enrichment | The name of the data provider or enrichment that was called |
| Cost | The number of credits or actions consumed by this request |
| Inputs | The values sent to the provider (e.g., email address, domain, company name) |
| Details | Full response payload or error message |
## Understanding request statuses
The request was successful and data was returned. The results have been written to the corresponding cells in your table.
The request reached the provider successfully, but no matching data was found for the given input. This is not an error. It simply means the provider does not have information for that particular query.
The request failed. Check the Details column for the specific error message and status code.
## Status codes reference
When a request fails, the status code helps identify the cause:
| Code | Meaning | What to do |
| ---- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200 | OK | Request succeeded. If cells are still empty, the provider returned no matching data for your input. Try different input values. |
| 400 | Bad Request | One or more input parameters are invalid. Check that the correct columns are mapped and that values are in the expected format. |
| 401 | Unauthorized | The API key is invalid or expired. If using your own key via a connector, verify it in your workspace settings. If using the API Network, contact support. |
| 404 | Not Found | The requested endpoint or resource does not exist. This is typically a platform-side issue. Contact support at [info@databar.ai](mailto:info@databar.ai). |
## General troubleshooting tips
The most common cause of "no data" results is malformed or unexpected input values. Verify that the column mapped to the enrichment contains clean, correctly formatted data.
Open the data logs panel and filter by **Error** status to see all failed requests. The Details column usually contains enough information to identify the problem.
Before running an enrichment on your entire table, test it on a single row. This lets you verify the configuration without consuming credits on a large batch.
If using a connector with your own key, make sure the key is still valid and has sufficient quota on the provider's side.
If you receive persistent 404 errors or unexpected behavior that you cannot resolve, reach out to the Databar team at [info@databar.ai](mailto:info@databar.ai).
## Related
Learn how enrichments work
Configure conditional logic for enrichment runs
Understand request costs
# Deduplication
Source: https://docs.databar.ai/product-guide/deduplication
Remove duplicate rows from your tables, manually or automatically.
Databar gives you three ways to remove duplicates from your tables: per-column deduplication, a one-off full-table cleanup, and automatic deduplication that prevents duplicates as new data arrives.
## Deduplicate by a single column
You can remove duplicates based on one specific column directly from the column header.
1. Click on the **column header** you want to deduplicate by.
2. Select **Remove duplicates** from the context menu.
Databar removes all rows that have duplicate values in that column, keeping only the first occurrence.
This operation is **irreversible**. It permanently deletes duplicate rows from your table.
## Remove all duplicates at once
You can also run a one-off deduplication check across all columns in your table.
1. Click the **Settings** button in the table toolbar.
2. Under the **De-duplication** section, click **Remove duplicates now**.
This checks every column in the table and removes any rows that are full duplicates across all columns.
## Auto de-duplication
Auto de-duplication runs continuously in the background and prevents duplicates from being added to your table in the first place. You can turn it on and off at any time.
To set it up:
1. Click the **Settings** button in the table toolbar.
2. Click **Auto de-duplication**.
3. Toggle **Automatic de-duplication** on.
4. Select the columns you want to check for duplicates. You can pick multiple columns.
5. Click **Save**.
### How auto de-duplication works
When you save your auto de-duplication settings, Databar immediately runs a "remove all duplicates" operation on the selected columns to clean up any existing duplicates in the table. From that point on, it checks incoming data on a rolling basis before it enters the table. If a new row matches an existing row on any of the selected columns, it is blocked from being added.
The order of operations matters: the table checks for duplicates first, cancels any duplicate rows, and only then runs enrichments on the remaining new rows. This means you never waste credits enriching data that would have been removed as a duplicate.
### When to use auto de-duplication
* Tables that receive continuous data from webhooks, imports, or scheduled runs
* Lead lists where you want to avoid contacting the same person twice
* Any table connected to an automated pipeline where duplicates could accumulate over time
## Comparing the three options
| Method | Scope | When it runs | Removes existing duplicates |
| --------------------- | ---------------- | ------------ | --------------------------------- |
| Column de-duplication | Single column | On demand | Yes |
| Remove all duplicates | All columns | On demand | Yes |
| Auto de-duplication | Selected columns | Continuously | Yes (on save) + prevents new ones |
## Related
Learn how tables work in Databar
Bring external data into your tables
# Enrichments
Source: https://docs.databar.ai/product-guide/enrichments
Automatically populate your tables with data from third-party providers.
Enrichments let you add new columns to your table by pulling data from third-party providers. Hand Databar 500 email addresses and it can return full names, job titles, company sizes, and locations without you touching a single API.
## Use cases
Enrichments work for any scenario where you have partial data and need to fill in the gaps:
* **SEO and content**: find which emails clicked on your content
* **Sales intelligence**: get estimated revenue and employee counts for target accounts
* **Competitive research**: scrape pricing pages and product catalogs
* **Prospecting**: find decision-maker emails from company domains
* **Data hygiene**: verify email addresses before launching outreach
## How to add an enrichment
Make sure your table has the data you want to enrich and that your column names are clean and descriptive. For example, if you plan to look up emails by domain, you need a column containing domains.
Click **Enrich** in the top-left corner of your table.
Browse or search the enrichment catalog. Each card shows what the enrichment does, which parameters it expects, and how many credits it costs per row.
Link each enrichment parameter to a column in your table. Databar tries to auto-populate inputs by matching your column names to the enrichment's parameters, so in many cases the mapping is already done for you. Type `{` inside a parameter field to see a list of available columns. Required parameters must be mapped before you can proceed; optional parameters can be left blank.
The enrichment returns a set of output fields. Choose which ones you want added to your table. You can always add or remove response columns later. Click **Add x Columns** to attach the enrichment and its output columns to your table.
Hit **Run** to process your rows. You can run all rows, run only empty rows, or run a single row to test.
## Column mapping
Every enrichment defines a set of input parameters. When you attach an enrichment to a table, you map those parameters to your columns so Databar knows which data to send for each row.
* **Required parameters** must be mapped to a column or given a static value.
* **Optional parameters** can be left empty. The enrichment will still run, but the provider may return fewer results.
Type `{` in any parameter field to reference a column by name.
## Response columns
Each enrichment returns structured data: fields like `email`, `phone`, `company_name`, `employee_count`, and so on. During setup you choose which fields become columns in your table. Adding more columns later does not re-run existing rows; only new runs populate the additional columns.
## Cell-level statuses
After a run, every enriched cell shows exactly what happened:
* **Completed**: the provider returned data for this row.
* **Error**: something went wrong (invalid input, provider timeout, etc.).
* **No data**: the provider ran successfully but had no result for this input.
These statuses are tracked per cell, so you can run multiple enrichments in parallel and see independent results for each one.
## Column grouping
When an enrichment adds many columns, Databar groups them under a single collapsible header to keep your table readable. Click the double-arrow button on a grouped column to expand it into individual columns.
## Credit costs
The enrichment sidebar shows the per-row credit cost before you run. A pricing preview estimates the total based on how many rows will be processed, so there are no surprises.
For details on how credits work and how to manage your balance, see [Credits and billing](/product-guide/credits-and-billing).
## Run strategies
When you click **Run**, you can choose how rows are processed:
| Strategy | Behavior |
| ------------------ | ----------------------------------------------------------------------------------------- |
| **Run all rows** | Processes every row in the table, including rows that already have results. |
| **Run empty only** | Skips rows that already have data for this enrichment. Useful after adding new rows. |
| **Run single row** | Processes one row so you can verify the enrichment works before committing to a full run. |
## Controlling which rows run
Use [run conditions](/product-guide/run-conditions) to write expressions that decide whether a row should be enriched. Rows that don't match are skipped and don't consume credits.
## Automating enrichments
Instead of clicking Run manually each time, you can set enrichments to run on a schedule or whenever source data changes. See [Automations](/product-guide/automations) for setup instructions.
## Next steps
Write conditional expressions to control which rows get enriched.
Schedule enrichment runs or trigger them automatically on data changes.
Understand how enrichment costs are calculated and billed.
Browse and run enrichments programmatically via the REST API.
# Exporters
Source: https://docs.databar.ai/product-guide/exporters
Push data from your Databar tables to external destinations.
Exporters let you send data from your Databar tables to external services, files, or APIs. Whether you need a quick CSV download or a live sync to your CRM, exporters handle the outbound side of your data workflow.
## Available export methods
Export your table as a **CSV** or **Excel** file. Click **Share/Export** in the table toolbar, select **Download**, and choose your format.
Send your table data to a new or existing Google Sheet.
Google Sheets accepts a maximum of 10 million cells (e.g., 20 columns x 500,000 rows). The maximum file size is 100 MB and each cell cannot contain more than 50,000 characters.
**Create a new Google Sheet**: Click the button to create a new Google Sheet with a snapshot of the table's current state. The sheet will not update automatically in the future.
**Insert into an existing Google Sheet**: To add data to a specific spreadsheet, you must first set the access level to **Editor** for **Anyone with the link**. In Google Sheets, click **Share**, then under **General access** select **Anyone with the link** and set the role to **Editor**. Copy the link and paste it into Databar.
Databar supports 20+ export destinations including CRM, outbound, and marketing platforms. A few examples:
* **HubSpot**: create or update contacts, companies, and deals
* **Salesforce**: push leads, contacts, and accounts
* **Pipedrive**: create or update persons, organizations, and deals
* **Instantly**, **Smartlead**, **Salesforge**, and more
This is far from a complete list. Visit the export panel in your table to see all available destinations.
Send data to any API endpoint by configuring a custom exporter. Define the URL, method, headers, and body mapping. See [Custom APIs](/product-guide/custom-apis) for details.
Push row data to any webhook URL. Useful for triggering downstream automations in n8n, Zapier, Make.com, or your own services.
## Setting up an exporter
Click **Share/Export** in the table toolbar.
Choose your export method: download, Google Sheets, a built-in integration, a custom API, or a webhook.
Link your table columns to the destination's expected fields. Exporters now **auto-map** columns to matching fields automatically, so you only need to adjust any mappings that were not matched correctly.
Set any destination-specific options (e.g., which HubSpot list to target, or whether to create vs. update records).
Click **Export** to send your data. You can export all rows, selected rows, or rows matching specific filters.
## Auto-mapping
When you set up an exporter, Databar automatically attempts to match your table columns to the destination's fields based on column names and types. This reduces manual field-matching and minimizes setup errors (the same behavior you already know from enrichment column mapping).
Review auto-mapped fields before running the export to make sure everything is linked correctly. Rename your table columns to match common field names (e.g., "email", "company\_name") for better auto-mapping accuracy.
## Exporter panel search
The exporter configuration panel includes a **local search** bar. Use it to quickly find and fill specific parameters without scrolling through long field lists. The search input stays active even after you click elsewhere in the panel.
## Next steps
Configure custom export destinations for any API endpoint.
Understand how tables and exporters work together.
Browse and manage exporters programmatically.
Bring data into Databar before exporting it.
# Folders
Source: https://docs.databar.ai/product-guide/folders
Organize your tables into folders within your workspace.
As your workspace grows, folders help you keep tables organized and easy to find. You can group tables by project, client, pipeline stage, or any structure that fits your workflow.
## Creating a folder
1. From your workspace home, click the **folder icon** button in the top-right corner of the page.
2. Enter a name for your folder.
3. The folder appears in your workspace alongside your tables.
## Moving tables into a folder
1. On the workspace home, use the **checkboxes** on the left side of your tables to select one or more tables.
2. Click **Move to folder** in the action bar that appears.
3. Choose the destination folder.
To move a table back out, open the folder, select the table with its checkbox, and move it to the workspace root.
## Renaming a folder
1. Open the folder by clicking on it.
2. Click the folder name at the top of the page to edit it.
3. Type the new name and confirm.
## Deleting a folder
Select a folder using the **checkbox** on the left, then click **Delete** in the action bar that appears. Tables inside the folder are moved back to the workspace root. They are not deleted.
Deleting a folder cannot be undone. Make sure you no longer need the organizational structure before removing it.
## Organization tips
| Strategy | When to use |
| ----------------- | ------------------------------------------------------------------------------- |
| By project | When you have distinct initiatives with their own datasets |
| By client | When managing data for multiple clients or accounts |
| By pipeline stage | When tables represent steps in a process (e.g., Raw leads, Enriched, Qualified) |
| By team | When multiple people share a workspace and need clear ownership |
Keep folder names short and consistent. A naming convention like `[Client] - [Project]` or `[Stage] - [Description]` makes it easy to scan at a glance.
## API access
You can also manage folders programmatically:
Retrieve all folders in your workspace
Create a new folder via the API
# Excel formulas
Source: https://docs.databar.ai/product-guide/formulas
Use familiar spreadsheet formulas directly in your Databar tables.
Databar supports Excel-style formulas natively, so you never need to export your data to a spreadsheet just to run simple calculations or logic. Add a formula column to any table and get instant, row-level results.
Formulas are a **transformation**. They are computed locally and do **not** consume any credits.
## How it works
Databar formulas use **column references** instead of traditional cell references. Instead of writing `A2` or `B2`, you reference columns by name using curly braces: `{column_name}`.
Each formula runs once per row, with the column references swapped for that row's values. This means every formula is effectively a single-row operation.
For example, if you have columns named `employee_count` and `first_name`, you would write:
```
=IF({employee_count}>100, "High", "Low")
```
## How to use
Navigate to the table where you want to add formula logic.
Click **Enrich**, then select **Formulas & Tools**. Choose **Excel Formula** from the list.
Enter any supported Excel formula, referencing columns by name using `{column_name}` syntax.
Results are computed instantly for every row in your table.
## Formula examples
Flag companies above a certain employee count:
```
=IF({employee_count}>100, "High", "Low")
```
Merge first name and last name into a full name:
```
=CONCATENATE({first_name}, " ", {last_name})
```
Combine multiple conditions for complex filtering:
```
=OR({country}="USA", {headcount}>500)
```
Round a value or find the max/min:
```
=ROUND({revenue}, 2)
=MAX({score_a}, {score_b})
```
## Available formulas
| Formula | Description | Example |
| ------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| `IF` | Returns one value if a condition is true, another if false | `=IF({score}>80, "Pass", "Fail")` |
| `OR` | Returns `TRUE` if any argument is true | `=OR({country}="USA", {country}="UK")` |
| `AND` | Returns `TRUE` if all arguments are true | `=AND({age}>18, {status}="active")` |
| `SUM` | Adds values together | `=SUM({q1_revenue}, {q2_revenue})` |
| `CONCATENATE` | Joins text strings into one | `=CONCATENATE({first_name}, " ", {last_name})` |
| `RANDBETWEEN` | Returns a random integer between two values | `=RANDBETWEEN(1, 100)` |
| `STDEV` | Calculates the standard deviation of values | `=STDEV({score_a}, {score_b}, {score_c})` |
| `EOMONTH` | Returns the last day of the month N months from a date | `=EOMONTH({start_date}, 3)` |
| `ROUND` | Rounds a number to a specified number of digits | `=ROUND({revenue}, 2)` |
| `MAX` | Returns the largest value from a set of arguments | `=MAX({bid_a}, {bid_b})` |
| `MIN` | Returns the smallest value from a set of arguments | `=MIN({price_1}, {price_2})` |
| `TODAY` | Returns today's date | `=TODAY()` |
| `LEN` | Returns the number of characters in a text string | `=LEN({description})` |
| `TRIM` | Removes leading and trailing spaces from text | `=TRIM({raw_name})` |
| `LOWER` | Converts text to lowercase | `=LOWER({email})` |
| `UPPER` | Converts text to uppercase | `=UPPER({ticker})` |
| `MID` | Extracts a substring from the middle of a text string | `=MID({phone}, 2, 3)` |
Looking for a different transformation? Use [JQ formulas](/product-guide/jq-formulas) to transform JSON data, [Table Lookup](/product-guide/table-lookup) for VLOOKUP-style enrichments across tables, [Split Text](/product-guide/split-text) to break a column into multiple columns, or [Merge Columns](/product-guide/merge-columns) to combine values from several columns into one.
## When to use formulas
* Quick math on numeric columns (revenue, headcount, scores)
* Concatenating text fields without a separate tool
* Building conditional flags or labels for filtering and segmentation
* Rounding, formatting, or normalizing values before export
## Related
Learn how tables work in Databar.
For JSON-level querying, use JQ expressions.
# Import data
Source: https://docs.databar.ai/product-guide/import-data
Bring data into Databar from CSV files, integrations, or webhooks.
Databar gives you multiple ways to get data into your tables: upload a file, connect a third-party service, receive webhooks, or add rows by hand. Choose the method that fits your workflow.
## CSV upload
Upload a comma-separated CSV file to create a new table or add data to an existing one.
Click **New table** from your workspace, then select **Import CSV**. Databar creates a table with columns and types inferred from your file.
Open the table you want to add data to, click **Import Data**, and select **CSV**. You will be prompted to map CSV columns to existing table columns or create new columns for any unmatched fields.
Only **comma-separated** CSV files are supported. If your file uses semicolons, pipes, or other delimiters, convert it to comma-separated format before uploading.
## Importers and integrations
The **Import Data** modal lists all available importers: direct connections to third-party services that pull data into your table automatically.
### Available importers
The list below is a sample of some available data sources. We add new integrations regularly, so this page may not reflect the latest options. Visit the [Integrations page](https://databar.ai/integrations) for the full, up-to-date list.
| Importer | What it imports |
| ---------------- | ----------------------------------------------------------- |
| **Calendly** | Scheduled events, invitee details, custom booking questions |
| **Attio** | Contacts, companies, and deals with custom attributes |
| **Salesforce** | Leads and contacts with standard and custom fields |
| **Instantly** | Leads across campaigns, contact details, engagement metrics |
| **HeyReach** | Leads from LinkedIn outreach campaigns |
| **Salesforge** | Contacts with sequence data |
| **Folk** | People and companies from Folk CRM |
| **Fireflies AI** | Meeting recordings, transcripts, and summaries |
| **tl;dv** | Meeting metadata, participants, and key moments |
| **HubSpot** | Contacts, companies, and deals |
| **Pipedrive** | Persons, organizations, and deals |
The Import Data modal displays all importers in a flat, searchable list, with no category tabs to navigate. Type to filter and find the integration you need instantly.
### Setting up an importer
Click **Import Data** in the table toolbar or from the workspace home.
Browse or search the list of available integrations and click the one you want.
Connect your account by following the OAuth flow or entering an API key, depending on the service.
Choose which records to import, map fields, and click **Import**. The data appears in your table immediately.
## Webhooks
Receive data from external systems in real time by creating a webhook endpoint for your table. Each incoming request creates a new row.
For setup instructions and configuration options, see the dedicated [Webhooks](/product-guide/webhooks) page.
## Manual entry
### Adding a single row
Click the **Add rows** button at the bottom of your table to append a new empty row. Fill in the cells manually.
### Adding multiple rows
Click the chevron next to **Add rows** to open the bulk-add menu. Specify the number of rows you want and choose whether to insert them at the top or bottom of the table.
There is no limit on how many rows you can add at once. Add as many as your workflow requires.
## Next steps
Set up webhook endpoints to receive data automatically.
Learn how tables, columns, and rows work in Databar.
Remove duplicate rows after importing data.
Enrich your imported data with third-party providers.
# Invite your team
Source: https://docs.databar.ai/product-guide/invite-your-team
Add team members to your workspace so you can collaborate on tables, enrichments, and data workflows.
Databar workspaces support multiple members. When you invite someone, they get access to all tables, folders, enrichments, and the shared credit balance in that workspace.
## Who can invite
Only the **workspace owner** can invite new members. If you need someone added and you are not the owner, ask the workspace owner to send the invitation.
## Inviting members
Click the **arrow** next to your workspace name in the top-left corner.
Select the **Invite your team** button from the dropdown menu.
Type one or more email addresses for the people you want to invite. You can invite multiple people at once.
Click **Invite**. Each person receives an email with a link to join your workspace.
## What happens next
* **Existing Databar users** are added to the workspace immediately.
* **New users** receive an invitation email. Once they create a Databar account and accept the invitation, they appear as active members.
## What members can access
All workspace members share:
* **Tables and folders**: every table and folder in the workspace is visible to all members.
* **Enrichments and waterfalls**: members can add, configure, and run enrichments.
* **Credit balance**: the workspace has a single credit pool shared across all members. Any enrichment run by any member draws from the same balance.
Members cannot change workspace-level settings (billing, API keys, credit alerts) or invite other users. Only the workspace owner has access to these controls.
## Viewing current members
In the **Team** section of workspace settings, you can see all current members along with their email, name, and status. The workspace owner is listed at the top.
## Removing a member
The workspace owner can remove a member from the Team settings page. Removing a member revokes their access to the workspace immediately. Their personal data and any other workspaces they belong to are not affected.
## Leaving a workspace
If you are a member (not the owner), you can leave a workspace at any time from your workspace list. Leaving removes your access to all tables and data in that workspace.
The workspace owner cannot leave their own workspace. To transfer ownership, contact [info@databar.ai](mailto:info@databar.ai).
## Plan requirements
Team collaboration requires a plan that supports multiple seats. Check [databar.ai/pricing](https://databar.ai/pricing) for details on which plans include multi-user access.
## Related
Configure API keys, alerts, and developer options
Understand how credits are shared across your team
# JQ formulas
Source: https://docs.databar.ai/product-guide/jq-formulas
Parse, filter, and manipulate JSON fields using JQ expressions.
JQ formulas let you apply [JQ](https://jqlang.org/) queries to any JSON column in your table. The result is written into a new column (stored as JSON), giving you full control over nested data without leaving Databar.
JQ formulas are a **transformation**. They do **not** consume any credits.
## What is JQ?
JQ is a lightweight command-line language designed for slicing, filtering, and transforming JSON data. It is particularly powerful when you need to dig into deeply nested objects or arrays that enrichment APIs return.
If you want to learn more, the [official manual](https://jqlang.org/manual/) is available, though it is fairly technical.
## Generate with AI
You don't need to learn JQ to use this feature. Databar has a built-in **Generate with AI** function that can write JQ expressions for you. Just describe what you need in plain language and the AI will generate the expression.
LLMs like ChatGPT and Claude are also excellent at generating JQ formulas. Describe your JSON structure and desired output, and they can produce a working expression in seconds.
## How to use
Open your table and add a new transformation column. Select **JQ Formula** from the list.
Choose which column contains the JSON data you want to query.
Enter your JQ expression. The query runs per row and the result is stored as JSON in the new column.
## Use cases
| Scenario | Example expression |
| -------------------------- | ------------------------------------------------------ |
| Count specific event types | `[.events[] \| select(.type == "purchase")] \| length` |
| Extract a nested value | `.company.funding.last_round.amount` |
| Build a structured output | `{name: .full_name, city: .address.city}` |
| Filter an array | `[.contacts[] \| select(.role == "CEO")]` |
## Related
Extract JSON values into separate columns visually.
Use spreadsheet formulas for simpler column logic.
# JSON expander
Source: https://docs.databar.ai/product-guide/json-expander
Extract values from JSON columns into separate, usable columns.
The JSON Expander extracts individual values from JSON columns and places them into their own columns, turning nested API response data into structured, usable table fields.
JSON Expander is a **transformation**. It does **not** consume any credits.
## How it works
Many enrichment APIs return complex JSON objects. The JSON Expander lets you visually browse those objects and select exactly which fields to extract, without writing any code.
Click any cell that contains JSON data in your table.
The JSON Expander opens in the right-side panel, keeping your table visible while you explore the JSON structure.
Browse the JSON structure and click **Map** next to any field to create a new column from that value. If the JSON contains a list of objects (e.g., `[{}, {}]`), you will also see a **Write to another table** option, which sends each item in the list as its own row into a separate table.
## Key capabilities
Map columns directly to nested JSON values without expanding into intermediate columns first.
Extract a full nested JSON object into a separate column, not just primitive text or number fields.
JSON Expander runs up to 6x faster than before. Values are processed in parallel for large tables.
The expander lives in the right-side panel so you can keep your table context visible while working.
## When to use JSON Expander vs. JQ formulas
| Scenario | Recommended tool |
| ------------------------------------------------------ | ----------------------------------------- |
| Quickly extract a few top-level or nested fields | JSON Expander |
| Filter arrays, count items, or build custom structures | [JQ formulas](/product-guide/jq-formulas) |
| Non-technical users who prefer a visual interface | JSON Expander |
| Complex transformations on deeply nested data | [JQ formulas](/product-guide/jq-formulas) |
## Related
Use JQ expressions for advanced JSON manipulation.
Learn how tables work in Databar.
# Low credit alerts
Source: https://docs.databar.ai/product-guide/low-credit-alerts
Set up email notifications when your workspace credit balance drops below a threshold.
Low credit alerts let you know when your workspace is running low on credits, so you can top up before enrichments are interrupted.
## How it works
You define a credit threshold. When your workspace balance drops below that number, the workspace owner receives an email notification. This gives you time to purchase additional credits before any running enrichments fail.
## Setting up an alert
Click the **arrow** next to your workspace name in the top-left corner, then select **Settings**.
Navigate to the **Billing** section in settings.
Enter the credit balance at which you want to be notified. For example, setting it to 500 means you get an email when your balance drops below 500 credits.
The alert is now active.
## Things to know
* Low credit alerts are **off by default**. You need to enable them manually.
* Only the **workspace owner** receives the notification email.
* The alert fires once when the balance crosses the threshold. It does not send repeated emails unless the balance recovers and drops again.
## What to do when you get an alert
When you receive a low credit notification, you can purchase additional credit packs from your [workspace settings](/product-guide/workspace-settings). Credit add-ons require an active subscription and expire 3 months after purchase.
For a full breakdown of how credits work, see [Credits and billing](/product-guide/credits-and-billing).
## Related
Understand credit costs and usage
Manage your workspace configuration
# Merge columns
Source: https://docs.databar.ai/product-guide/merge-columns
Combine multiple columns into one using smart fallback logic.
Merge Columns lets you combine multiple columns into a single output column using priority-based fallback logic. Databar picks the first non-empty value from your ordered list of source columns, giving you a clean, consolidated result.
Merge Columns is a **transformation**. It does **not** consume any credits.
## When to use
When the same data point exists across multiple columns (often because you enriched from different providers), you end up with fragmented values. For example, you might have a company name from Apollo, another from Clearbit, and a third from your CRM import. Merge Columns resolves this into one authoritative column.
## How to use
Open your table, add a new transformation column, and select **Merge Columns**.
Choose the columns you want to merge. The order matters. Databar will use the first non-empty value it finds, working from top to bottom.
A new column appears with the best available value for each row.
## Example
Suppose you have three columns for company website:
| Website (Apollo) | Website (Clearbit) | Website (Import) |
| ---------------- | ------------------ | ---------------- |
| - | acme.com | acme.io |
| globex.com | - | globex.net |
With Merge Columns set to priority order Apollo → Clearbit → Import, the result column would contain:
| Merged Website |
| -------------- |
| acme.com |
| globex.com |
The first non-empty value wins.
## Related
Learn how tables work in Databar.
Use formulas for more complex merging logic.
# n8n integration
Source: https://docs.databar.ai/product-guide/n8n-integration
Connect Databar to n8n workflows for enrichments, waterfalls, and table operations.
Connect the full power of Databar to n8n. Run enrichments, execute waterfalls, and manage table data directly inside your n8n workflows to enrich leads, sync data, and monitor your account without writing API calls by hand.
## Prerequisites
* An active [Databar](https://databar.ai) account
* An n8n instance (Cloud or self-hosted, version 1.0+)
* A Databar API key (found in your workspace under **Integrations**)
## Installation
The Databar node is available on the official n8n marketplace. In your n8n instance:
1. Go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-databar`
4. Confirm the installation
The Databar node will appear in your node panel. If the node doesn't appear, you may need to restart your n8n instance.
Install via npm in your n8n installation directory:
```bash theme={null}
npm install n8n-nodes-databar
```
Then restart n8n.
## Setting up credentials
Open any workflow and add a Databar node.
Click the **Credential** dropdown and select **Create New**. Enter your Databar API key.
Click **Save**. The connection gets tested automatically. When successfully tested, n8n should display that you have been successfully authorized.
The API key gives access to all resources in that workspace. If you have multiple workspaces, create separate credentials for each. Your API key is found in your Databar workspace under **Integrations**.
## Resources and operations
The Databar node organizes functionality into four resources:
| Resource | Operations | Description |
| -------------- | -------------------------- | --------------------------------------------------------- |
| **Enrichment** | Run | Enrich a single record using any Databar enrichment |
| **Table** | Insert Rows, Upsert Rows | Add or update rows in your Databar tables |
| **Waterfall** | Run | Run a waterfall across multiple data providers |
| **Other** | Get Account Info, Get Task | Check your account balance or retrieve async task results |
Use this to enrich a single record: look up a person by email, verify a phone number, get company data from a domain, and more. There are over 450 enrichments currently available.
### How to configure
1. Set **Resource** to Enrichment
2. Set **Operation** to Run
3. Select an **Enrichment** from the dropdown. Browse all available enrichments with descriptions and credit costs.
4. Fill in the **Parameters**. The form is generated dynamically based on the enrichment you selected. Required fields are marked.
5. Choose whether to **Wait for Completion** (enabled by default). This mode is highly preferred to avoid complexity in the integration.
### Parameters
| Parameter | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enrichment** | The enrichment to run. The dropdown is searchable; type to filter. Each option shows the name, data source, and credit cost. |
| **Parameters** | Input fields specific to the selected enrichment. These are generated dynamically. For example, an email verifier shows an "Email" field, while a company lookup shows a "Domain" field. |
| **Wait for Completion** | When enabled (default), the node waits for the enrichment to finish and returns the results directly. When disabled, it returns a `task_id` immediately that you can check later. |
**Additional options** (when Wait for Completion is enabled):
| Option | Default | Description |
| ------------- | ----------- | -------------------------------------------------- |
| Poll Interval | 3 seconds | How often to check if the enrichment has completed |
| Timeout | 300 seconds | Maximum time to wait before the node gives up |
### Example: Enrich a contact by email
1. Add a Databar node to your workflow
2. Resource: **Enrichment**, Operation: **Run**
3. Select "Get people data from email" from the enrichment dropdown
4. Enter the email address in the Email field (or map it from a previous node)
5. Execute the node
The output will contain the enriched contact data: name, company, social profiles, and more, depending on the enrichment.
### Tips
* You can map values from previous nodes into any parameter field using n8n expressions
* Each enrichment costs a certain number of credits, shown in the dropdown
* If you need to enrich many records, connect a loop or use n8n's built-in batching. The node processes one item per execution.
Use this to add new rows to a Databar table. Each input item in your workflow creates one row.
### How to configure
1. Set **Resource** to Table
2. Set **Operation** to Insert Rows
3. Select a **Table** from the dropdown
4. Fill in the **Fields**. The form shows all columns in your table with their types (e.g., name (text), revenue (number)).
### Parameters
| Parameter | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Table** | Select the target table. The dropdown is searchable and shows all tables in your workspace. |
| **Fields** | One input field per column in the table. Each field label shows the column name and type. Only user-created columns are shown; enrichment-generated columns are filtered out. |
**Options** (click Add Option to configure):
| Option | Default | Description |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Allow New Columns | false | When enabled, if your data includes column names that don't exist in the table yet, Databar will create them automatically as text columns. |
| Dedupe | false | When enabled, rows that match existing rows on specified keys will be skipped instead of creating duplicates. |
| Dedupe Keys | - | Comma-separated list of column names to use for duplicate detection (e.g., `domain, email`). Only shown when Dedupe is enabled. |
### Example: Insert leads from a webhook
1. Set up a **Webhook** node to receive lead data
2. Add a Databar node: Resource **Table**, Operation **Insert Rows**
3. Select your leads table
4. Map the webhook fields to table columns (e.g., `{{ $json.name }}` into the Name field)
5. Execute. Each incoming webhook creates a new row.
Use this to update an existing row if it matches a key, or insert a new row if no match is found. This is useful for keeping your table in sync with external data.
### How to configure
1. Set **Resource** to Table
2. Set **Operation** to Upsert Rows
3. Select a **Table** from the dropdown
4. Choose a **Column to Match On**. This is the column Databar will use to find existing rows.
5. Enter the **Value to Search**. The specific value to look for in that column.
6. Fill in the **Fields**. The column values to set on the matched or newly created row.
### Parameters
| Parameter | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Table** | The target table. |
| **Column to Match On** | The column used to find an existing row. The dropdown shows all user-created columns in the table. |
| **Value to Search** | The value to look for in the match column. Databar searches for a row where the column matches this value exactly. If found, that row is updated. If not found, a new row is created. |
| **Fields** | The column values to set. Works the same as Insert Rows: one field per column, with types shown. |
### Example: Sync CRM data
1. Use a **Schedule Trigger** to run daily
2. Fetch contacts from your CRM
3. Add a Databar node: Resource **Table**, Operation **Upsert Rows**
4. Select your contacts table
5. Set **Column to Match On** to `email`
6. Map the email from the CRM data into **Value to Search**
7. Map the other CRM fields into the column fields
8. Execute. Existing contacts are updated, new ones are inserted.
A waterfall tries multiple data providers in sequence until one returns a successful result. This is useful when you need high coverage: if one provider doesn't have the data, the next one is tried automatically.
### How to configure
1. Set **Resource** to Waterfall
2. Set **Operation** to Run
3. Select a **Waterfall** from the dropdown
4. Fill in the **Parameters**. The form is generated dynamically based on the waterfall's input requirements.
5. Select **Data Providers**. Choose which providers to include in the waterfall (required).
6. Choose whether to **Wait for Completion** (enabled by default).
### Parameters
| Parameter | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Waterfall** | The waterfall to run. The dropdown shows all waterfalls in your workspace. |
| **Parameters** | Input fields specific to the selected waterfall. For example, a "Find email by name and company" waterfall shows fields for First Name, Last Name, and Domain. |
| **Data Providers** | Multi-select dropdown showing all available providers for this waterfall. You must select at least one. Providers are tried in order; the waterfall stops at the first successful result. Each provider shows its name and credit cost. |
| **Wait for Completion** | When enabled (default), the node waits for the waterfall to finish. When disabled, returns a `task_id` immediately. |
**Additional options** (when Wait for Completion is enabled):
| Option | Default | Description |
| ------------- | ----------- | ------------------------------------------------- |
| Poll Interval | 3 seconds | How often to check if the waterfall has completed |
| Timeout | 300 seconds | Maximum time to wait |
### Example: Find someone's email
1. Add a Databar node
2. Resource: **Waterfall**, Operation: **Run**
3. Select a "Find email" waterfall
4. Fill in the person's name and company domain
5. Select the data providers you want to try
6. Execute. Returns the email from the first provider that finds it.
A simple utility operation to check your account status.
### How to configure
1. Set **Resource** to Other
2. Set **Operation** to Get Account Info
3. Execute
### Output
Returns your account details including:
* Account name and email
* Current credit balance
* Plan information
* Workspace details
This is useful for monitoring your credit usage in automated workflows.
Retrieve the status and results of an async task. This is useful when you run enrichments or waterfalls with **Wait for Completion** disabled and need to check results later.
### How to configure
1. Set **Resource** to Other
2. Set **Operation** to Get Task
3. Enter the **Task ID** returned by a previous enrichment or waterfall run
4. Execute
### Parameters
| Parameter | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| **Task ID** | The ID of the task to check, returned when running an enrichment or waterfall with Wait for Completion disabled. |
### Output
Returns the task status and results. If the task has completed, the response includes the enrichment or waterfall output data.
Task results are stored for **1 hour** after completion. Retrieve your results before they expire.
## Working with expressions
Most fields in the Databar node support n8n expressions, letting you dynamically pass data from previous nodes. Individual parameter fields within enrichments, waterfalls, and table operations can be mapped to values from earlier nodes.
### Mapping data from a previous node
In any field, click the Expression toggle and use standard n8n syntax:
```
{{ $json.email }} // value from the previous node
{{ $('Webhook').item.json.domain }} // value from a specific node
{{ $json.name.split(' ')[0] }} // JavaScript transformations
```
### Using dynamic table or enrichment IDs
If you need to select a table or enrichment dynamically (e.g., based on input data), switch the dropdown to Expression mode by clicking the three-dot menu next to the field, then enter an expression that resolves to the ID.
## Error handling
| Error | Cause | Solution |
| ---------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Authentication failed | Invalid or expired API key | Check your API key in credentials. Generate a new one in Databar under **Integrations** if needed. |
| Task timed out | Enrichment or waterfall took longer than the timeout | Increase the timeout in Additional Options, or disable Wait for Completion and poll separately. |
| No enrichments loading | API connectivity issue | Check your internet connection and verify your API key has the correct permissions. |
| Fields not appearing | No table selected | Select a table first. Column fields load dynamically after table selection. |
To handle failures gracefully, enable **Continue On Fail** in the node settings. When enabled, failed executions output an `error` field on the main output instead of stopping the workflow, letting you log errors or retry with different parameters.
## Workflow examples
### Lead enrichment pipeline
**Webhook > Databar (Enrichment: Run) > IF (qualified?) > Slack Notification**
Enrich incoming leads with company data, filter by criteria, and notify your team.
### Data sync with deduplication
**Schedule > Google Sheets (Read) > Databar (Table: Insert Rows, Dedupe on email)**
Periodically sync data from a spreadsheet into a Databar table, skipping duplicates.
### Multi-provider email finder
**Manual Trigger > Databar (Waterfall: Run) > Databar (Table: Upsert Rows)**
Find emails using a waterfall of providers, then store results in a table, updating existing rows if the person is already there.
### Credit monitoring
**Schedule (daily) > Databar (Other: Get Account Info) > IF (credits \< 100) > Email Alert**
Check your credit balance daily and get notified when it's running low.
## FAQ
Credit costs depend on the specific enrichment or data provider. Costs are shown in the enrichment and provider dropdowns when configuring the node.
Yes. Connect a node that outputs multiple items (like a spreadsheet read or database query) before the Databar node. The node processes each item individually.
The node returns the task response with empty or null result fields. Your workflow can check for this and handle it accordingly.
Yes. The Databar node is available on the official n8n marketplace and works on both n8n Cloud and self-hosted instances running v1.0 or later.
In your Databar workspace, go to **Integrations**. Each workspace has its own API key.
## Next steps
Learn how enrichments work in Databar
Chain providers for maximum data coverage
Understand how Databar tables store and organize data
# Run conditions
Source: https://docs.databar.ai/product-guide/run-conditions
Control which rows get enriched using conditional expressions.
Run conditions are expressions that Databar evaluates for every row before running an enrichment. If the expression returns **true**, the row is processed. If it returns **false**, the row is skipped.
This gives you two advantages:
* **Better data quality**: only enrich rows that meet your criteria, so you don't waste processing on irrelevant data.
* **Lower cost**: skipped rows do not consume credits.
## Generate with AI
You don't need to learn CEL syntax to use run conditions. Databar includes a built-in AI generator that writes the expression for you. Just describe what you want in plain English and the AI will produce the corresponding formula.
For example, type "only run on rows where the country is US and the company has more than 50 employees" and the AI will generate `{country} == "US" && {employee_count} >= 50`.
You can also use LLMs like ChatGPT or Claude to help write CEL expressions. Just describe your table columns and the filtering logic you need.
## Syntax basics
Run conditions are written using **CEL (Common Expression Language)**, an open expression language created by Google. To reference a column in your table, type `{` and select the column name.
```
{country} == "US" && {employee_count} >= 50
```
The expression above runs the enrichment only for US-based companies with 50 or more employees.
## Operator reference
### Comparison operators
| Operator | Meaning | Example |
| -------- | --------------------- | ------------------------ |
| `==` | Equal to | `{country} == "US"` |
| `!=` | Not equal to | `{status} != "inactive"` |
| `>` | Greater than | `{lead_score} > 80` |
| `<` | Less than | `{employee_count} < 500` |
| `>=` | Greater than or equal | `{revenue} >= 1000000` |
| `<=` | Less than or equal | `{founded_year} <= 2010` |
### Combining multiple conditions
Use logical operators to chain multiple conditions together in a single run condition expression.
| Operator | Meaning | Example |
| -------- | --------------------------------------- | -------------------------------------------------------------------- |
| `&&` | AND: all conditions must be true | `{country} == "US" && {employee_count} >= 50` |
| `\|\|` | OR: at least one condition must be true | `{title} == "CEO" \|\| {title} == "CTO"` |
| `!` | NOT: exclude rows matching a condition | `!{website}.contains("test")` |
| `( )` | Group conditions together | `({country} == "US" \|\| {country} == "CA") && {revenue} >= 1000000` |
### Text operators
| Operator | Meaning | Example |
| ------------------- | ---------------------------- | ---------------------------------- |
| `.contains("x")` | True if text contains "x" | `{email}.contains("@gmail.com")` |
| `.startsWith("x")` | True if text starts with "x" | `{phone}.startsWith("+1")` |
| `.endsWith("x")` | True if text ends with "x" | `{domain}.endsWith(".io")` |
| `.size()` | Number of characters | `{email}.size() > 0` |
| `.matches("regex")` | Regex match | `{email}.matches("^.+@.+\\..+$")` |
| `.lowerAscii()` | Convert to lowercase | `{country}.lowerAscii() == "us"` |
| `.upperAscii()` | Convert to uppercase | `{code}.upperAscii() == "USA"` |
| `+` | Join text | `{first_name} + " " + {last_name}` |
### Math operators
| Operator | Meaning |
| -------- | ------------------ |
| `+` | Addition |
| `-` | Subtraction |
| `*` | Multiplication |
| `/` | Division |
| `%` | Modulo (remainder) |
### List operators
| Operator | Meaning | Example |
| ----------------------- | -------------------------- | -------------------------------------------- |
| `"x" in list` | True if "x" is in the list | `"VIP" in {tags}` |
| `.size()` | Number of items | `{tags}.size() > 0` |
| `.exists(x, condition)` | At least one item matches | `{tags}.exists(t, t.contains("enterprise"))` |
| `.all(x, condition)` | Every item matches | `{tags}.all(t, t != "")` |
### Handling empty values
| Operator | Meaning | Example |
| -------------- | ------------------------------ | ------------------------------------------------ |
| `has(column)` | True if the column has a value | `has({email}) && {email}.contains("@gmail.com")` |
| `column != ""` | True if not empty text | `{email} != ""` |
Always check for empty values before calling text operators like `.contains()` or `.startsWith()`. Calling these on an empty cell can cause unexpected behavior.
## Examples
### Simple conditions (single rule)
| Goal | Expression |
| -------------------- | -------------------------------- |
| Only Gmail addresses | `{email}.contains("@gmail.com")` |
| High-scoring leads | `{lead_score} > 80` |
| US-based companies | `{country} == "US"` |
| Skip empty emails | `{email} != ""` |
| VIP-tagged contacts | `"VIP" in {tags}` |
| Skip test websites | `!{website}.contains("test")` |
### Combining two conditions
| Goal | Expression |
| -------------------------------- | --------------------------------------------------------- |
| US companies with 50+ employees | `{country} == "US" && {employee_count} >= 50` |
| Active leads with high scores | `{status} == "active" && {lead_score} > 80` |
| Email present and valid format | `{email} != "" && {email}.contains("@")` |
| CEOs or CTOs only | `{title} == "CEO" \|\| {title} == "CTO"` |
| High revenue or Series B funding | `{revenue} >= 5000000 \|\| {funding_stage} == "Series B"` |
### Combining three conditions
| Goal | Expression |
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
| C-level execs at large US companies | `{country} == "US" && {employee_count} >= 500 && {title}.contains("Chief")` |
| US or Canada, 50+ employees | `({country} == "US" \|\| {country} == "CA") && {employee_count} >= 50` |
| Active enterprise leads with email | `{status} == "active" && {plan} == "enterprise" && {email} != ""` |
| Skip test, demo, and example domains | `!{domain}.contains("test") && !{domain}.contains("demo") && !{domain}.contains("example")` |
### Combining four or more conditions
| Goal | Expression |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enterprise targets in North America with budget | `({country} == "US" \|\| {country} == "CA") && {employee_count} >= 200 && {revenue} >= 1000000 && {status} == "active"` |
| Qualified SaaS leads | `{industry} == "SaaS" && {employee_count} >= 50 && {lead_score} > 70 && has({email})` |
| Senior decision-makers at funded companies | `({title}.contains("VP") \|\| {title}.contains("Director") \|\| {title}.contains("Chief")) && {funding_stage} != "" && {employee_count} >= 100 && {country} == "US"` |
## Tips
Before running an enrichment with a new condition across thousands of rows, use the **Run single row** option or filter your table to a small subset. This lets you verify the condition behaves as expected without spending credits.
When mixing `&&` and `||`, wrap groups in parentheses so the evaluation order is clear. Without parentheses, `&&` binds more tightly than `||`, which can produce unexpected results.
```
// Ambiguous
{country} == "US" || {country} == "CA" && {revenue} >= 1000000
// Clear
({country} == "US" || {country} == "CA") && {revenue} >= 1000000
```
Use `has({column})` or `{column} != ""` before operating on a column that might be empty. This prevents errors from calling `.contains()` or `.startsWith()` on a null value.
CEL is type-aware. If a column stores numbers as text, you may need to convert with `int()` before comparing:
```
int({employee_count}) >= 50
```
Similarly, text comparisons are case-sensitive by default. Use `.lowerAscii()` to normalize.
Rows that fail a run condition are not sent to the data provider and do not consume credits. Use conditions aggressively to keep costs predictable.
## FAQ
Yes. You combine multiple conditions in a single expression using `&&` (AND) and `||` (OR) operators. For example, `{country} == "US" && {employee_count} >= 50 && {email} != ""` checks three conditions at once. There is no limit to how many conditions you can chain together. See [Combining multiple conditions](#combining-multiple-conditions) for the full syntax.
No. Rows that fail a run condition are never sent to the data provider and do not consume any credits.
Yes. Run conditions work with both single enrichments and [waterfalls](/product-guide/waterfalls). The condition is evaluated before the waterfall starts, so skipped rows don't trigger any providers.
## Next steps
Learn how to add and run enrichments on your tables.
Combine run conditions with scheduled or event-driven automation.
# Send data between tables
Source: https://docs.databar.ai/product-guide/send-between-tables
Move rows from one table to another within your workspace.
Sending data between tables lets you move rows from one table to another inside your workspace. This is useful for building multi-step workflows where each stage of your pipeline lives in its own table.
## Use cases
* **Multi-step pipelines**: move raw leads into a "Qualified leads" table after scoring, then into an "Enriched leads" table after enrichment.
* **Separating source and output data**: keep imported data untouched in one table while sending processed results to another.
* **Appending automation results**: route rows produced by automations or enrichments into a dedicated dataset for review.
## How to set up
Click **Share/Export** in the table toolbar, then select **Send to another Databar table**.
Select an existing table from your workspace or choose **Create new table** to set up a fresh destination.
Map the columns from your source table to the corresponding columns in the destination table. Use consistent column names across tables for easier mapping.
Click **Install** to save the configuration. Rows will be sent to the destination table based on your mapping.
Sending a row copies it to the destination table. The original row remains in the source table.
## Tips for multi-table workflows
* **Name your tables by stage** (e.g., "Raw leads", "Verified leads", "Enriched leads") to keep your pipeline easy to follow.
* **Use consistent column names** across tables so values map automatically when sending rows.
* **Combine with automations** to trigger enrichments or exports as soon as data lands in a destination table.
## Next steps
Learn how tables work in Databar.
Reference data from other tables without moving rows.
Automatically enrich rows in your destination table.
Push data from any table to external services.
# Split text to columns
Source: https://docs.databar.ai/product-guide/split-text
Split combined values into separate columns by a delimiter.
Split Text takes a single column containing combined values and separates it into multiple columns based on a delimiter you choose. This is useful when imported data packs multiple fields into one cell.
Split Text is a **transformation**. It does **not** consume any credits.
## How to use
Open your table, add a new transformation column, and select **Split Text to Columns**.
Choose the column that contains the combined values you want to split.
Pick the character that separates the values. The delimiter field is pre-filled with `" "` (space) by default. Options include:
* Space (`" "`)
* Dash (`-`)
* Comma (`,`)
* Any custom character
To use a space as the delimiter, enter it with quotes: `" "`. This is already the default value when you open the configuration.
Set how many output columns you want. Excess parts beyond the limit stay in the last column. The split produces a JSON value, which you can then work with further using the [JSON Expander](/product-guide/json-expander) or [JQ formulas](/product-guide/jq-formulas).
## Example
A column containing `"John Doe, CEO"` split by comma into 2 parts produces:
| Part 1 | Part 2 |
| -------- | ------ |
| John Doe | CEO |
## Common delimiter scenarios
| Original value | Delimiter | Result columns |
| --------------------- | --------- | --------------------------- |
| `Jane Smith` | Space | `Jane` / `Smith` |
| `2024-01-15` | Dash | `2024` / `01` / `15` |
| `New York, NY, 10001` | Comma | `New York` / `NY` / `10001` |
| `first@example.com` | `@` | `first` / `example.com` |
## Related
Learn how tables work in Databar.
Combine multiple columns back into one.
# Table lookup
Source: https://docs.databar.ai/product-guide/table-lookup
Pull matching values from another table, like VLOOKUP in a spreadsheet.
Table Lookup lets you enrich any table by pulling in matching values from another table in your workspace. Think of it as VLOOKUP built natively into Databar: no formulas, no exports, no manual copy-pasting between sheets.
Table Lookup is found under **Enrich** → **Formulas & Tools**. It uses your existing Databar tables as the lookup source.
## How to use
Click **Enrich**, then select **Formulas & Tools**. Choose **Table Lookup** from the list.
Choose which table in your workspace contains the data you want to pull in.
Select which column in the target table should be searched for matches.
Choose how values should be compared:
* **Contains**: partial match (useful for names, domains)
* **Equals**: exact match (useful for IDs, emails)
Define which value from your current table to look up. You can use dynamic column references with the `{column_name}` syntax.
The matched result from the target table lands as a new column in your current table.
## Use cases
| Scenario | How it helps |
| ---------------------------------- | ------------------------------------------------------------------- |
| Cross-referencing CRM exports | Match contacts across a marketing list and a CRM export by email |
| Combining enriched data | Pull company details from one enriched table into another by domain |
| Excluding competitors | Look up a blocklist table and flag matches for removal |
| Joining datasets on a shared field | Connect any two tables that share a common identifier |
## Dynamic column references
When mapping the lookup value, use curly braces to reference columns dynamically:
```
{Email}
{Company Domain}
```
This pulls the value from the specified column for each row, just like a formula reference.
## Related
Learn about all available enrichment options.
Learn how tables work in Databar.
# Tables
Source: https://docs.databar.ai/product-guide/tables-overview
How to create, configure, and work with tables in Databar.
Tables are the core data structure in Databar. Each table is a collection of rows and columns where you store, enrich, and transform your data. Tables support **unlimited rows**, infinite scroll, cell-level enrichment tracking, and flexible column types.
There is no row limit on Databar tables. You can store and enrich as many rows as you need, with no caps or restrictions on table size.
## Creating tables
You can create a new table in several ways:
Click **New table** from your workspace home to start with an empty table. Add columns and rows manually, or attach enrichments to populate data automatically.
Import a CSV file to create a table pre-populated with your existing data. Column types are inferred automatically. Free plans support CSV uploads up to 5 MB, while higher plans support up to 200 MB per upload.
Connect to CRMs, outbound tools, analytics platforms, and list-builders to pull data directly into a new table. See [Import data](/product-guide/import-data) for details.
Generate a webhook URL for your table and send data to it from any external system. Each incoming payload creates new rows automatically. See [Webhooks](/product-guide/webhooks) for setup details.
You can also create tables programmatically via the [Tables API](/api-reference/endpoint/tables-create).
## Columns
Add columns by clicking the **+** button at the end of the header row. Click any column header to rename, delete, change type, or sort. Enrichment columns are created automatically and grouped under collapsible headers.
Databar supports 11 column types including Text, Number, Currency, Boolean/Checkbox, Date, Datetime, URL, Image, JSON, Select, and Multiple choice.
Learn about column types, management, and grouping
## Rows
### Adding rows
* **Single row**: click **Add row** at the bottom of the table.
* **Bulk add**: paste multiple values or use an importer to add hundreds or thousands of rows at once.
* **Programmatic**: use the [Tables API](/api-reference/endpoint/tables-insert-rows) to insert rows from scripts or automations.
### Editing cells
Click any cell to edit its value directly. For JSON columns, use the expanded editor for easier navigation of nested structures. You can also use the [JSON Expander](/product-guide/json-expander) to flatten nested fields into their own columns.
### Row detail view
Click the expand icon on any row to open the sidebar detail view. This shows all column values for that row in a vertical layout, making it easier to inspect complex or wide tables.
### Infinite scroll
Tables load rows progressively as you scroll. There is no pagination. Just keep scrolling to see more data, even for tables with tens of thousands of rows.
## Cell-level enrichment statuses
Each cell populated by an enrichment displays a status indicator (success, no data, error, loading, run conditions not met, or inputs missing) so you can spot issues at a glance. Hover over any error icon to see the details inline.
Full reference for all cell statuses, data logs, status codes, and troubleshooting steps
## Filtering and sorting
* **Sort**: click any column header to sort ascending or descending.
* **Filter**: use the filter bar above the table to show only rows matching specific conditions (e.g., "Status equals Error" or "Email is not empty").
Filters and sorts can be combined and are applied client-side for instant feedback.
## Data formatting
Databar automatically handles common formatting needs:
* **UNIX timestamps** are converted to human-readable dates.
* **Booleans** display as checkmarks or crosses.
* **Image URLs** render inline previews.
* **Long text** is truncated in the cell with full content visible in the detail view.
## Working with JSON columns
Many API providers return nested JSON objects. Databar provides a **JSON expander** that lets you flatten specific fields from a JSON column into their own top-level columns. This makes it easy to extract exactly the data you need without manual parsing. See the [JSON Expander](/product-guide/json-expander) page for details.
## Next steps
Attach data providers to your table columns
Bring data in from external sources
Troubleshoot enrichment errors
Create and manage tables programmatically
# Waterfalls
Source: https://docs.databar.ai/product-guide/waterfalls
Chain multiple data providers with automatic fallback for maximum coverage.
Want to use waterfalls programmatically? Check out the [Waterfalls API reference](/api-reference/endpoint/waterfalls-list) or use them directly from the [MCP Server](/mcp-server).
A waterfall chains multiple data providers together and tries them one by one until one returns a result. If the first provider has no data, the next is tried automatically. This continues down the chain until a provider succeeds or all have been exhausted.
This gives you the highest possible data coverage from a single operation, without manually running and merging results from multiple sources.
## Why use waterfalls
No single data provider covers every record. One service might find 60% of emails, another a different 50%, and a third might cover niche domains the others miss. Waterfalls automate the fallback logic so you define the provider order once and Databar handles the rest.
## Available waterfalls
Databar ships several pre-built waterfalls. Each one is purpose-built for a specific enrichment use case.
The list of waterfalls and data providers below may not be fully up to date. We ship updates frequently and may have added new waterfalls or providers since this page was last updated. Check the enrichment panel in your table for the latest options.
Find a work email address from a person's name and the company they work at.
**Input**
| Parameter | Required | Description |
| ---------- | -------- | ---------------------------------- |
| First name | Yes | The first name of the person |
| Last name | Yes | The last name of the person |
| Company | Yes | The company name or website domain |
**Output**
| Field | Type |
| ----- | ---- |
| Email | Text |
**Providers**
[Snov.io](https://databar.ai/explore/snov-api) ·
[Icypeas](https://databar.ai/explore/icypeas) ·
[Leadmagic](https://databar.ai/explore/leadmagic-api) ·
[Datagma](https://databar.ai/explore/datagma) ·
[Hunter.io](https://databar.ai/explore/hunterio-api) ·
[Prospeo](https://databar.ai/explore/prospeo-api) ·
[Findymail](https://databar.ai/explore/findymail-api) ·
[RocketReach](https://databar.ai/explore/rocketreach-api) ·
[People Data Labs](https://databar.ai/explore/people-data-labs-api)
This waterfall supports **email verification**. When enabled, each found email is checked for deliverability before being accepted. If the email fails verification, the waterfall moves on to the next provider.
Get work and personal email addresses from a social profile link (typically a LinkedIn URL).
**Input**
| Parameter | Required | Description |
| --------- | -------- | ------------------------------------ |
| Link | Yes | A social profile URL (e.g. LinkedIn) |
**Output**
| Field | Type |
| -------------- | ---- |
| First name | Text |
| Last name | Text |
| Work email | Text |
| Personal email | Text |
**Providers**
[Prospeo](https://databar.ai/explore/prospeo-api) ·
[Muraena](https://databar.ai/explore/muraena) ·
[Findymail](https://databar.ai/explore/findymail-api) ·
[Leadmagic](https://databar.ai/explore/leadmagic-api) ·
[Pubrio](https://databar.ai/explore/pubrio) ·
[RocketReach](https://databar.ai/explore/rocketreach-api) ·
[ContactOut](https://databar.ai/explore/contactout) ·
[Forager](https://databar.ai/explore/forager) ·
[People Data Labs](https://databar.ai/explore/people-data-labs-api)
This waterfall also supports **email verification**, with the same behavior as the Email by name waterfall.
Enrich a person's profile from their email address. Returns identity, job, and company information.
**Input**
| Parameter | Required | Description |
| --------- | -------- | ------------------------------- |
| Email | Yes | The email address of the person |
**Output**
| Field | Type |
| ------------ | ---- |
| First name | Text |
| Last name | Text |
| LinkedIn URL | Text |
| Job title | Text |
| Country | Text |
| Company data | JSON |
| Education | JSON |
**Providers**
[Diffbot](https://databar.ai/explore/diffbot-api) ·
[Snov.io](https://databar.ai/explore/snov-api) ·
[Datagma](https://databar.ai/explore/datagma) ·
[Forager](https://databar.ai/explore/forager) ·
[People Data Labs](https://databar.ai/explore/people-data-labs-api) ·
[RocketReach](https://databar.ai/explore/rocketreach-api)
Get a phone number from a LinkedIn profile URL.
**Input**
| Parameter | Required | Description |
| --------- | -------- | -------------------------------------- |
| LinkedIn | Yes | The LinkedIn profile URL of the person |
**Output**
| Field | Type |
| ----- | ---- |
| Phone | Text |
**Providers**
[Leadmagic](https://databar.ai/explore/leadmagic-api) ·
[Databar Labs](https://databar.ai/explore/databar-labs) ·
[Pubrio](https://databar.ai/explore/pubrio) ·
[Prospeo](https://databar.ai/explore/prospeo-api) ·
[Upcell](https://databar.ai/explore/upcell) ·
[Limadata](https://databar.ai/explore/limadata) ·
[People Data Labs](https://databar.ai/explore/people-data-labs-api) ·
[Datagma](https://databar.ai/explore/datagma) ·
[Forager](https://databar.ai/explore/forager) ·
[Findymail](https://databar.ai/explore/findymail-api)
Get firmographic data about a company from its website URL, including employee count, funding, revenue, and industry.
**Input**
| Parameter | Required | Description |
| --------------- | -------- | ------------------------------ |
| Company website | Yes | The website URL of the company |
**Output**
| Field | Type |
| ------------------- | ---- |
| Company name | Text |
| Description | Text |
| LinkedIn link | Text |
| Number of employees | Text |
| Address | JSON |
| Industries | Text |
| Est. revenue | Text |
| Funding | JSON |
**Providers**
[Diffbot](https://databar.ai/explore/diffbot-api) ·
[Owler](https://databar.ai/explore/owler-api) ·
[Muraena](https://databar.ai/explore/muraena) ·
[ContactOut](https://databar.ai/explore/contactout) ·
[People Data Labs](https://databar.ai/explore/people-data-labs-api)
Resolve a company name to its website URL. Useful as a preparatory step before running other company-based waterfalls.
**Input**
| Parameter | Required | Description |
| ------------ | -------- | ----------------------- |
| Company name | Yes | The name of the company |
**Output**
| Field | Type |
| ----------- | ---- |
| Company URL | Text |
**Providers**
[Databar APIs](https://databar.ai/explore/databar-labs) ·
[People Data Labs](https://databar.ai/explore/people-data-labs-api)
Get active job listings from a company's website, including titles, links, descriptions, and locations.
**Input**
| Parameter | Required | Description |
| --------------- | -------- | ------------------------------ |
| Company website | Yes | The website URL of the company |
**Output**
| Field | Type |
| ------------ | ----------------------------------------------------- |
| Job postings | JSON (title, link, description, location per posting) |
**Providers**
[PredictLeads](https://databar.ai/explore/predictleads-api) ·
[Leadmagic](https://databar.ai/explore/leadmagic-api)
## Setting up a waterfall
Adding a waterfall to your table works similarly to adding a single [enrichment](/product-guide/enrichments):
Click **Enrich** in the top-left corner of your table, then select **Add a new Enrichment** and switch to the **Waterfalls** tab.
Select the waterfall you want to use. The setup sidebar will appear. Categories that include waterfalls are marked with a small waterfall icon.
Click on **Waterfall setup** to expand the provider configuration. Here you can see all available data providers for this waterfall, each showing its name, logo, and credit cost.
You can customize the waterfall in three ways:
* **Reorder providers** by dragging the provider cards up or down. The order determines which provider is tried first.
* **Toggle providers** on or off. Click a provider card to enable or disable it. Disabled providers are skipped during execution.
* **Add an email verifier** (email waterfalls only). Toggle the "Verify email" switch and select a verification service.
Under **Mapping**, map each required input parameter to a column in your table or enter a static value.
Click **Run** (or **Install waterfall** for new setups) to process your rows.
All standard table features work with waterfalls: [run conditions](/product-guide/run-conditions), [automations](/product-guide/automations), cell-level statuses, and run strategies (run all, run empty, run single row).
## Email verification
The **Email by name** and **Email by link** waterfalls support optional email verification. When enabled, each time a provider returns an email, the verifier checks its deliverability before the waterfall accepts it. If the email fails verification, the waterfall continues to the next provider instead of returning an undeliverable address.
Available email verifiers:
* [**Emailable**](https://databar.ai/explore/emailable-api)
* [**Bouncer**](https://databar.ai/explore/bouncer-api)
* [**Zerobounce**](https://databar.ai/explore/zerobounce-api)
Each verifier has its own credit cost, shown in the setup sidebar. You can choose whichever verifier you prefer.
When a provider returns an email that fails verification, the waterfall moves on to the next provider, but you are still charged for the successful run on the original provider. The provider did return a result; it just didn't pass the verification step. Keep this in mind when estimating costs, as verification can increase the total credits consumed per row.
## Provider ordering and cost optimization
Providers are tried from top to bottom. The waterfall stops at the first provider that returns a usable result. This means provider order directly affects your cost per lookup.
Place your cheapest or highest-coverage providers first. For example, if Provider A costs 1 credit and covers 40% of records while Provider B costs 3 credits and covers 70%, putting Provider A first means you only pay the higher price for the 60% of records that Provider A misses.
## Using waterfalls headlessly
You can run waterfalls programmatically without a table using the REST API, Python SDK, CLI, or MCP server.
```bash theme={null}
curl -X POST "https://api.databar.ai/v1/waterfalls/WATERFALL_ID/run" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"params": {
"first_name": "Jane",
"last_name": "Doe",
"company": "acme.com"
}
}'
```
See the full [Waterfalls API reference](/api-reference/endpoint/waterfalls-list) for all endpoints.
```python theme={null}
from databar import DatabarClient
client = DatabarClient()
result = client.run_waterfall_sync(WATERFALL_ID, {
"first_name": "Jane",
"last_name": "Doe",
"company": "acme.com"
})
print(result)
```
See the [Python SDK docs](/python-sdk) for setup and additional methods.
See the [CLI documentation](/cli) for running waterfalls from the command line.
See the [MCP waterfall skill](/mcp-skill-waterfall) for using waterfalls with AI agents.
For bulk runs, use the [bulk endpoint](/api-reference/endpoint/waterfalls-bulk-run) to process multiple records in a single request.
Task data from headless runs is stored for **24 hours**. Retrieve and save your results before they expire.
## Related
Learn how single-provider enrichments work
Browse and run waterfalls programmatically
# Webhooks
Source: https://docs.databar.ai/product-guide/webhooks
Receive data from external services into your Databar tables automatically.
Webhooks let you receive data from external applications (such as n8n, Zapier, Make.com, or your own backend) directly into a Databar table. Each incoming HTTP request creates a new row, making webhooks ideal for real-time data pipelines.
**Example:** Push the email address of every newly registered user from your website into a Databar table, then automatically enrich each row with company data, job titles, and social profiles.
## Instant setup
Clicking **Webhooks** from the workspace home instantly creates a new table with a webhook pre-configured and the setup panel already open. Your unique webhook URL is ready to copy. No extra steps required.
You can also add a webhook to an existing table by clicking **Import Data** in the table toolbar and selecting **Webhooks**.
## Setting up a webhook
Click **Import Data** in the table toolbar and select **Webhooks**, or use the instant-setup option from the workspace home.
Give the webhook a descriptive name so you can identify it later (e.g., "New signups from marketing site").
Your unique URL is displayed in the setup panel. Copy it. You will configure your external service to POST data to this URL.
Select one of two modes:
The full webhook payload is written into a single JSON column. You can unpack specific fields later using the [JSON Expander](/product-guide/json-expander).
Send a test request to your webhook URL first. Databar inspects the payload and lets you map individual fields to specific table columns.
In your external tool (n8n, Zapier, Make.com, or your own code), set the destination URL to the webhook URL you copied. Make sure the request method is **POST** and the content type is **application/json**.
Send a test request and confirm that a new row appears in your table with the expected data.
If you don't see data appear right away, refresh the page.
## How webhooks work
* Each POST request to your webhook URL creates **one new row** in the linked table.
* The webhook accepts JSON payloads. Non-JSON requests are rejected.
* Webhook URLs are unique per table and persist until you delete the webhook.
* Webhooks are unlimited on all paid plans.
Webhooks are receive-only endpoints. To **send** data from Databar to external services, use [Exporters](/product-guide/exporters).
## Common integrations
| Service | How to connect |
| ------------------ | ---------------------------------------------------------------------------------------- |
| **n8n** | Add an HTTP Request node with your webhook URL as the destination. |
| **Zapier** | Use the "Webhooks by Zapier" action and paste your webhook URL. |
| **Make.com** | Add an HTTP module pointing to your webhook URL. |
| **Custom backend** | Send a POST request with a JSON body to your webhook URL from any language or framework. |
## Next steps
Explore all methods for getting data into Databar.
Unpack raw JSON webhook payloads into individual columns.
Learn how tables work and how webhooks fit in.
Automatically enrich rows as they arrive via webhook.
# What is Databar?
Source: https://docs.databar.ai/product-guide/what-is-databar
The data platform for enrichment, automation, and integration. Use it from the UI, API, SDK, CLI, or directly inside AI agents via MCP.
Databar is a data platform that connects to 160+ APIs, web scrapers, and third-party services so you can collect, enrich, and act on structured data without building pipelines. Use it however fits your workflow: through the visual table interface, the REST API, the Python SDK, the CLI, or directly inside AI agents like Claude via the MCP server.
At its core, Databar gives you keyless access to a network of data providers. Point at a data source, run it, and get results back in seconds. Tables are the primary way most users interact with Databar, but the same enrichment and waterfall engine is available programmatically for developers who want to integrate it into their own applications and automations.
## Core capabilities
Store and manage structured data with columns, filters, and cell-level enrichment statuses.
Combine your existing data with third-party providers to fill in the gaps automatically.
Access 100+ keyless data providers through the API Network. Pay per use with credits.
REST API, Python SDK, CLI, and MCP server for programmatic access.
## How it works
Databar combines several building blocks into a single workflow:
* **[Enrichments](/product-guide/enrichments)**: attach data providers to your table columns. When you run an enrichment, each row is sent to the provider and the results are written back into your table.
* **[Waterfalls](/product-guide/waterfalls)**: chain multiple providers together with automatic fallback. If the first provider returns no data, the next one picks up.
* **[Connectors](/product-guide/custom-apis)**: bring your own API keys for services you already pay for, or add entirely custom endpoints.
* **[Exporters](/product-guide/exporters)**: push enriched data to HubSpot, Salesforce, Google Sheets, webhooks, or other tables.
* **Formulas**: transform data in-place with [Excel formulas](/product-guide/formulas), [JQ expressions](/product-guide/jq-formulas), [merge columns](/product-guide/merge-columns), [deduplication](/product-guide/deduplication), and [Table Lookup](/product-guide/table-lookup) (VLOOKUP across tables).
## AI features
* **[AI Researcher](/product-guide/ai-researcher)**: an autonomous agent that finds and compiles information across the web for each row in your table.
* **[AI Prompt Templates](/product-guide/ai-prompts)**: run custom prompts against your data using LLMs, with configurable templates and variables.
## Extensions and integrations
* **[Chrome Extension](/product-guide/chrome-extension)**: collect structured data from any website directly into a Databar table.
* **[Google Sheets Extension](/product-guide/google-sheets-extension)**: run Databar enrichments without leaving your spreadsheet.
* **[n8n Integration](/product-guide/n8n-integration)**: connect Databar to n8n workflows for complex automation scenarios.
* **[Webhooks](/product-guide/webhooks)**: receive data from external systems instantly, with zero-config webhook URLs per table.
## Who is Databar for?
Databar is built for teams that need structured data but don't want to maintain pipelines:
* **Sales and RevOps**: enrich leads, verify contact info, score accounts
* **Marketing**: build prospect lists, research competitors, monitor mentions
* **Recruiting and HR**: source candidates, verify profiles, track outreach
* **E-commerce**: monitor pricing, aggregate product data, track suppliers
* **Anyone with a data workflow**: the platform is flexible enough to handle any scenario where you need to collect, enrich, or transform structured data
## Recent additions
Databar ships updates frequently. Check out our [changelog](https://feedback.databar.ai/changelog) to see the latest features and improvements.
## Get started
Create your first table
Quickstart for the REST API
Install the Python SDK
Connect via MCP
Learn about enrichments
Understand pricing
# Workspace settings
Source: https://docs.databar.ai/product-guide/workspace-settings
Configure your workspace and manage preferences.
The workspace settings page is where you manage workspace-level configuration, including billing, team access, and usage preferences.
## Accessing settings
Click the **arrow** next to your workspace name in the top-left corner, then select **Workspace Settings** from the dropdown menu.
## Workspaces and the workspace switcher
Every Databar user has their own **personal workspace** that is created automatically when they sign up. This personal workspace is on the free plan by default.
When someone invites you to a team workspace, you gain access to that workspace's plan, credits, tables, and features. However, you still land in your personal workspace when you log in. To access the team workspace (and its paid features), you need to switch to it.
### Switching workspaces
Click the **arrow** next to your workspace name in the top-left corner. At the bottom of the dropdown, you will see all workspaces you have access to. Click on a workspace to switch to it.
If you were invited to a team workspace but don't see the features or credits you expected, make sure you have switched to the correct workspace. Your personal workspace is separate and runs on its own (free) plan.
## Team and collaboration
If your plan supports multiple seats, you can invite team members to your workspace. Team members share all tables, folders, enrichments, and the workspace credit balance.
Learn how to add team members to your workspace
## Related
Understand credit costs and purchase add-ons
Get notified when your credit balance is running low
# Python SDK
Source: https://docs.databar.ai/python-sdk
Install the official Databar Python SDK and start enriching data in minutes.
## Installation
```bash theme={null}
pip install databar
```
Requires Python 3.9+. Dependencies (`httpx`, `pydantic`, `typer`, `rich`) are installed automatically.
***
## Authentication
Get your API key from your [Databar workspace](https://databar.ai) → **Integrations**.
```bash theme={null}
export DATABAR_API_KEY=your-key-here
```
```python theme={null}
from databar import DatabarClient
client = DatabarClient() # reads DATABAR_API_KEY automatically
```
```python theme={null}
from databar import DatabarClient
client = DatabarClient(api_key="your-key-here")
```
***
## Quickstart
```python theme={null}
from databar import DatabarClient
client = DatabarClient()
# Check your balance
user = client.get_user()
print(f"Balance: {user.balance} credits | Plan: {user.plan}")
# Find enrichments
enrichments = client.list_enrichments(q="linkedin")
for e in enrichments:
print(f" [{e.id}] {e.name} — {e.price} credits")
# Run an enrichment (submit + poll in one call)
result = client.run_enrichment_sync(123, {"email": "alice@example.com"})
print(result)
```
***
## Enrichments
```python theme={null}
# List all enrichments
enrichments = client.list_enrichments()
# Search by keyword
enrichments = client.list_enrichments(q="phone number")
for e in enrichments:
print(f"[{e.id}] {e.name} — {e.price} credits/call")
```
```python theme={null}
enrichment = client.get_enrichment(123)
print(enrichment.name)
print(enrichment.description)
for param in enrichment.params:
required = "required" if param.is_required else "optional"
print(f" {param.name} ({param.type_field}, {required}): {param.description}")
for field in enrichment.response_fields:
print(f" → {field.name} ({field.type_field})")
```
```python theme={null}
# Async — returns immediately with a task ID
task = client.run_enrichment(123, {"email": "alice@example.com"})
print(task.task_id) # poll this later
# Sync — submits and waits for completion in one call
result = client.run_enrichment_sync(123, {"email": "alice@example.com"})
print(result)
```
```python theme={null}
inputs = [
{"email": "alice@example.com"},
{"email": "bob@example.com"},
{"email": "carol@example.com"},
]
# Sync — submits and waits for all results
results = client.run_enrichment_bulk_sync(123, inputs)
# Results are aligned to inputs: one element per input, in input order,
# with None for inputs that returned no data (len(results) == len(inputs)).
for lead, result in zip(inputs, results):
if result is None:
print(f"{lead['email']}: no data")
else:
print(f"{lead['email']}: {result}")
```
```python theme={null}
# For enrichments with select/multiselect parameters
choices = client.get_param_choices(123, "country", q="united")
for choice in choices.items:
print(f" {choice.id}: {choice.name}")
if choices.has_next_page:
next_page = client.get_param_choices(123, "country", page=2)
```
***
## Waterfalls
Waterfalls chain multiple enrichment providers together with automatic fallback — if provider A doesn't return a result, provider B is tried automatically.
```python theme={null}
waterfalls = client.list_waterfalls()
for w in waterfalls:
providers = len(w.available_enrichments)
print(f"{w.identifier}: {w.name} ({providers} providers)")
```
```python theme={null}
# Uses all available providers by default
result = client.run_waterfall_sync(
"email_getter",
{"linkedin_url": "https://linkedin.com/in/alice"}
)
print(result)
# Or specify providers explicitly
result = client.run_waterfall_sync(
"email_getter",
{"linkedin_url": "https://linkedin.com/in/alice"},
enrichments=[10, 11, 12] # provider IDs from get_waterfall()
)
```
```python theme={null}
inputs = [
{"linkedin_url": "https://linkedin.com/in/alice"},
{"linkedin_url": "https://linkedin.com/in/bob"},
]
results = client.run_waterfall_bulk_sync("email_getter", inputs)
print(results)
```
***
## Tables
```python theme={null}
# Create a table with predefined columns
table = client.create_table(
name="My Leads",
columns=["email", "name", "company", "linkedin_url"]
)
print(f"Created: {table.identifier}")
# List all tables
tables = client.list_tables()
for t in tables:
print(f"{t.identifier}: {t.name}")
```
```python theme={null}
# Get rows with pagination
data = client.get_rows(table.identifier, page=1, per_page=500)
```
```python theme={null}
from databar import InsertRow, InsertOptions, DedupeOptions
rows = [
InsertRow(fields={"email": "alice@example.com", "name": "Alice"}),
InsertRow(fields={"email": "bob@example.com", "name": "Bob"}),
]
# With deduplication on email column
response = client.create_rows(
table.identifier,
rows,
options=InsertOptions(
allow_new_columns=True,
dedupe=DedupeOptions(enabled=True, keys=["email"])
)
)
created = [r for r in response.results if r.action == "created"]
skipped = [r for r in response.results if r.action == "skipped_duplicate"]
print(f"Inserted {len(created)}, skipped {len(skipped)} duplicates")
```
Large inserts are auto-batched in chunks of 50 — no manual chunking needed.
```python theme={null}
from databar import BatchUpdateRow
rows = [
BatchUpdateRow(id="row-uuid-1", fields={"name": "Alice Smith"}),
BatchUpdateRow(id="row-uuid-2", fields={"name": "Bob Jones"}),
]
response = client.patch_rows(table.identifier, rows)
```
```python theme={null}
from databar import UpsertRow
rows = [
UpsertRow(key={"email": "alice@example.com"}, fields={"name": "Alice", "company": "Acme"}),
UpsertRow(key={"email": "new@example.com"}, fields={"name": "New User"}),
]
response = client.upsert_rows(table.identifier, rows)
for r in response.results:
print(f"{r.id}: {r.action}") # "created" or "updated"
```
***
## Tasks
For async operations, you can check task status manually or poll until complete:
```python theme={null}
# Submit without waiting
task = client.run_enrichment(123, {"email": "alice@example.com"})
print(f"Task submitted: {task.task_id}")
# Check status once
status = client.get_task(task.task_id)
print(status.status) # "processing", "completed", "failed", or "gone"
# Poll until complete (blocks until done or times out)
result = client.poll_task(task.task_id)
print(result)
```
***
## Error handling
```python theme={null}
from databar import (
DatabarClient,
DatabarAuthError,
DatabarNotFoundError,
DatabarInsufficientCreditsError,
DatabarTaskFailedError,
DatabarTimeoutError,
)
try:
result = client.run_enrichment_sync(123, {"email": "alice@example.com"})
except DatabarAuthError:
print("Invalid API key — check your DATABAR_API_KEY")
except DatabarInsufficientCreditsError:
print("Out of credits — top up at databar.ai")
except DatabarNotFoundError:
print("Enrichment not found")
except DatabarTaskFailedError as e:
print(f"Enrichment failed: {e.message}")
except DatabarTimeoutError as e:
print(f"Timed out after {e.max_attempts} polls — task may still be running")
```
| Exception | HTTP Status | When raised |
| --------------------------------- | ----------- | ----------------------------------------- |
| `DatabarAuthError` | 401 / 403 | Invalid or missing API key |
| `DatabarNotFoundError` | 404 | Enrichment, waterfall, or table not found |
| `DatabarInsufficientCreditsError` | 406 | Not enough credits |
| `DatabarGoneError` | 410 | Task results expired (stored 24 hours) |
| `DatabarValidationError` | 422 | Invalid request parameters |
| `DatabarRateLimitError` | 429 | Rate limit exceeded |
| `DatabarTaskFailedError` | — | Task status returned `failed` |
| `DatabarTimeoutError` | — | Polling exceeded max attempts |
***
## Configuration
```python theme={null}
client = DatabarClient(
api_key="...", # default: DATABAR_API_KEY env var
base_url="https://api.databar.ai/v1", # default
timeout=30, # seconds per request (default: 30)
max_poll_attempts=150, # polling attempts before timeout (default: 150)
poll_interval_s=2.0, # seconds between polls (default: 2.0)
)
```
The client also works as a context manager — connection pool is closed automatically:
```python theme={null}
with DatabarClient() as client:
result = client.run_enrichment_sync(123, {"email": "alice@example.com"})
```
***
## Source code
The SDK is open source under the MIT License.
View source, report issues, and contribute on GitHub.
# REST API Quickstart
Source: https://docs.databar.ai/quickstart-rest
Make your first Databar API call in under 5 minutes.
## 1. Get your API key
Log in to your [Databar workspace](https://databar.ai) and navigate to **Integrations** to find your API key.
API access requires an active paid subscription. Free plans do not include API access.
## 2. Verify your key
Test that your API key works by fetching your account info:
```bash cURL theme={null}
curl https://api.databar.ai/v1/user/me \
-H "x-apikey: YOUR_API_KEY"
```
```python Python SDK theme={null}
from databar import DatabarClient
client = DatabarClient(api_key="YOUR_API_KEY")
user = client.get_user()
print(f"{user.first_name} - {user.balance} credits")
```
```bash CLI theme={null}
databar login --api-key YOUR_API_KEY
databar whoami
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.databar.ai/v1/user/me", {
headers: { "x-apikey": "YOUR_API_KEY" }
});
const data = await response.json();
console.log(data);
```
You should receive a response like:
```json theme={null}
{
"first_name": "David",
"email": "david@databar.ai",
"balance": 100.0,
"plan": "Pro"
}
```
## 3. Search for an enrichment
Find available enrichments by searching with a keyword:
```bash cURL theme={null}
curl "https://api.databar.ai/v1/enrichments/?q=email" \
-H "x-apikey: YOUR_API_KEY"
```
```python Python SDK theme={null}
enrichments = client.list_enrichments(q="email")
for e in enrichments:
print(f"[{e.id}] {e.name} - {e.price} credits")
```
```bash CLI theme={null}
databar enrich list --query "email"
```
## 4. Run an enrichment
Once you have an enrichment ID, run it with the required parameters:
```bash cURL theme={null}
curl -X POST "https://api.databar.ai/v1/enrichments/123/run" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"params": {"email": "test@example.com"}}'
```
```python Python SDK theme={null}
result = client.run_enrichment_sync(123, {"email": "test@example.com"})
print(result)
```
```bash CLI theme={null}
databar enrich run 123 --params '{"email": "test@example.com"}'
```
## 5. Run in bulk
For batch processing, use the bulk endpoint:
```bash cURL theme={null}
curl -X POST "https://api.databar.ai/v1/enrichments/123/bulk-run" \
-H "x-apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"params": [{"email": "a@example.com"}, {"email": "b@example.com"}]}'
```
```python Python SDK theme={null}
results = client.run_enrichment_bulk_sync(123, [
{"email": "a@example.com"},
{"email": "b@example.com"},
])
print(results)
```
```bash CLI theme={null}
databar enrich bulk 123 --input leads.csv --format csv --out results.csv
```
Bulk operations return a `task_id`. Check progress with:
```bash theme={null}
curl "https://api.databar.ai/v1/tasks/YOUR_TASK_ID" \
-H "x-apikey: YOUR_API_KEY"
```
Task data is stored for **24 hours** after completion. Make sure to retrieve your results before they expire.
## Next steps
Explore all endpoints with request and response examples.
Full SDK reference with enrichments, waterfalls, tables, and error handling.
Walkthrough: enrich a list of leads with company and contact data.
Walkthrough: find emails using multiple providers with automatic fallback.