# Update many records at once

> Set field values on every record that matches your conditions with one REST API call, and count the matching records before you run it.

Source: https://tadabase.com/docs/developers/batch-operations  
Status: Verified Nov 17, 2026. Checked against the current product

The batch update sets the same values on every record of a table that matches your conditions, in one request. Count the matching records first with `records/batch-update-check`, then run `records/batch-update`.

## Before you start

- The API key needs **Allow Updates**.
- The update runs at once, on the database, and the API answers when it is done.
- It does not recalculate equations or rollups, does not run workflows or webhooks, and does not write record logs for the changed records. To refresh equations afterwards, see [Recalculate equations through the API](https://tadabase.com/docs/developers/formulas-and-equations).
- There is no undo. Count first, and test your conditions on a list request.

## Step 1: Count the matching records

Send the same conditions you will use for the update, as `filters` in the query string (the format of [Filter records in API requests](https://tadabase.com/docs/developers/filtering-records)):

```bash
curl -G "https://api.tadabase.io/api/v1/data-tables/{tableId}/records/batch-update-check" \
  -H "X-Tadabase-App-id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET" \
  --data-urlencode "filters[items][0][field_id]=field_38" \
  --data-urlencode "filters[items][0][operator]=is" \
  --data-urlencode "filters[items][0][val]=Pending"
```

```json
{ "type": "success", "total": 25, "msg": "" }
```

## Step 2: Run the update

Post `conditions` and `values` as JSON:

```bash
curl -X POST "https://api.tadabase.io/api/v1/data-tables/{tableId}/records/batch-update" \
  -H "X-Tadabase-App-id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "condition": "AND", "items": [ { "field_id": "field_38", "operator": "is", "val": "Pending" } ] }
    ],
    "values": [
      { "field_id": "field_38", "value": "Approved" },
      { "field_id": "field_39", "value": "2026-11-17" }
    ]
  }'
```

```js
const BASE = 'https://api.tadabase.io/api/v1';
const headers = {
  'X-Tadabase-App-id': 'YOUR_APP_ID',
  'X-Tadabase-App-Key': 'YOUR_API_KEY',
  'X-Tadabase-App-Secret': 'YOUR_API_SECRET',
};

const res = await fetch(`${BASE}/data-tables/${tableId}/records/batch-update`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    conditions: [{ condition: 'AND', items: [{ field_id: 'field_38', operator: 'is', val: 'Pending' }] }],
    values: [{ field_id: 'field_38', value: 'Approved' }],
  }),
});
const result = await res.json();
if (result.type !== 'success') throw new Error(result.msg);
console.log(`${result.total} records changed`);
```

```json
{ "type": "success", "total": 25, "msg": "" }
```

`total` is the number of records whose values changed. It can be lower than the count from step 1 when some records already had the new values.

## Conditions

- `conditions` is one filter group, or a list of groups. When you send several groups, a record must match every group.
- Each group has `items` (each with `field_id`, `operator` and `val`), an optional `condition` of `AND` or `OR`, and optional nested groups in `child`. The operators are the ones in [Filter records in API requests](https://tadabase.com/docs/developers/filtering-records).
- You can send `filters` instead of `conditions`, but not both.
- To update every record in the table, send `"all": true` and no conditions. Without conditions and without `"all": true`, the request is refused.
- A condition with an unknown field or operator refuses the whole request, so a typo never widens the update.

## Values

Each entry in `values` names a field by its slug (or field ID) in `field_id` and gives the new value in `value`. To clear a field, send `{"field_id": "field_39", "val_type": "blank_value"}`.

| Field type | Value |
| --- | --- |
| Text, Email, Phone, Long Text, Select, Radio | Text |
| Rich Text | HTML text (sanitized as in a single save) |
| Number, Currency | A number |
| Decision Box | `1`, `true`, `yes` or `on` for checked; `0`, `false`, `no` or `off` for unchecked |
| Multi-Select, Checkbox | An array of options |
| Date, Date/Time, Time | A date or time, as in a single save. A value that is not a date clears the field. |
| Name, Address | An object with the parts to set, such as `{"city": "Springfield"}`. Parts you leave out keep their values. |
| JSON | A JSON value. Invalid JSON refuses the request. |

These field types cannot be set by a batch update, and a request that includes one is refused: Date Range, File, Files, Image, Signature, Equation, Rollup, formula fields, Auto Increment and passwords. Do not use a batch update for connection fields either; update connections one record at a time.

## Errors

A refused batch update answers HTTP 200 with `"type": "error"` and a `msg` that says why, so always check `type`. For example:

- "Add conditions, or send "all": true to update every record in this table."
- "Send either conditions or filters, not both."
- "Condition 1 in group 1 isn't valid (field or operator not recognised)."
- "None of the submitted values matched a field in this table. ..." when no `field_id` names a field of the table.

A key without **Allow Updates** gets HTTP 412.
