---
title: "table.ai.apply: Write an AI field's results — Table kit command — Kition"
description: "Writes what the host's model generated (text, images or errors per record) into an AI field."
canonical: "https://developer.kition.ai/docs/kits/table/commands/table.ai.apply"
---

> Canonical HTML: [https://developer.kition.ai/docs/kits/table/commands/table.ai.apply](https://developer.kition.ai/docs/kits/table/commands/table.ai.apply)

# table.ai.apply

**Write an AI field's results.** Writes what the host's model generated (text, images or errors per record) into an AI field.

- Kit: Table 0.4.0 (.ktable); reference: [Table kit commands](https://developer.kition.ai/docs/kits/table.md)
- Changes the document: yes

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | `string` | no | The AI action (summarize, translate, extract, improve, customize, classify, text_generation, image_generation, image_customization); when given, it must be the field's own. |
| `asOrigin` | `string` | no | system:<name> writes as a host feature, outside the undo history. Agents leave it out. |
| `config` | `object` | no | Overrides of the field's AI configuration for this run. |
| `fieldId` | `integer \| string` | yes | The AI field's id. |
| `recordId` | `integer \| string` | no | One record to run on. |
| `results` | `object[]` | yes | What the host generated, one entry per record. |
| `tableId` | `integer \| string` | yes | The table's id. |

## Call through table_run

```text
table_run {
  "path": "<file>.ktable",
  "steps": [{ "command": "table.ai.apply", "params": { "tableId": <integer | string>, "fieldId": <integer | string>, "results": <object[]> } }]
}
```

The required parameters, with placeholders for their types: not a tested example. Optional: `action`, `asOrigin`, `config`, `recordId`. table_run answers the step’s result in `completed[i].result`.

## Result

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `change` | `object \| null` | no | What the call changed, or null. |
| `error` | `object` | no | Why the call failed (A18); the file is as it was. |
| `result` | `object` | no | What was written: one record's `record`, `field` and `state`, or a batch's `items` and counts. |

```json
{
  "additionalProperties": false,
  "description": "The request's own answer is in `result`, beside `change`: what the call changed in the document (null when nothing changed). A failed call answers `error` instead (A18).",
  "properties": {
    "change": {
      "description": "What the call changed, or null.",
      "oneOf": [
        {
          "additionalProperties": false,
          "description": "What one projection changed in the relational tables, by integer id. Every list is sorted and\nholds no repeats.",
          "properties": {
            "dashboards": {
              "description": "A dashboard, or the base's list of them, changed.",
              "type": "boolean"
            },
            "documentId": {
              "type": "string"
            },
            "origin": {
              "description": "Who wrote it: kind:principal, or a system origin's label.",
              "type": "string"
            },
            "recordsDeleted": {
              "description": "[tableId, rowKey] pairs.",
              "items": {
                "items": {},
                "type": "array"
              },
              "type": "array"
            },
            "recordsReordered": {
              "description": "Tables whose records' positions changed.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            "recordsUpserted": {
              "description": "[tableId, rowKey] pairs.",
              "items": {
                "items": {},
                "type": "array"
              },
              "type": "array"
            },
            "schema": {
              "description": "Tables whose fields were added, removed, updated, or reordered.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            "tables": {
              "description": "Tables whose own row changed: created, deleted, renamed, moved, or given a new primary\nfield.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            "views": {
              "description": "Views created, deleted, updated, or reordered, or whose column widths or visibility\nchanged.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            }
          },
          "required": [
            "tables",
            "schema",
            "views",
            "recordsReordered",
            "dashboards"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "additionalProperties": false,
      "description": "Why the call failed (A18); the file is as it was.",
      "properties": {
        "code": {
          "enum": [
            "invalid-params",
            "invalid-op",
            "invalid-value",
            "not-found",
            "read-only",
            "unknown-command",
            "command-failed",
            "not-open",
            "draft-required",
            "not-allowed",
            "unsupported",
            "unavailable",
            "failed"
          ],
          "type": "string"
        },
        "index": {
          "description": "The failing step or operation.",
          "type": "integer"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "result": {
      "additionalProperties": true,
      "description": "What was written: one record's `record`, `field` and `state`, or a batch's `items` and counts.",
      "properties": {
        "accepted": {
          "description": "Results taken (a batch).",
          "type": "integer"
        },
        "completed": {
          "description": "Records written.",
          "type": "integer"
        },
        "errors": {
          "items": {
            "additionalProperties": true,
            "description": "A result that failed.",
            "properties": {
              "message": {
                "description": "Why.",
                "type": "string"
              },
              "record_id": {
                "description": "The record's id.",
                "type": "integer"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "failed": {
          "description": "Results that failed.",
          "type": "integer"
        },
        "field": {
          "additionalProperties": true,
          "description": "A field (column).",
          "properties": {
            "ai_prompt": {
              "description": "A legacy AI prompt.",
              "type": "string"
            },
            "created_at": {
              "description": "When it was created, in Unix milliseconds.",
              "type": "integer"
            },
            "document_id": {
              "description": "Always 1: the document's id.",
              "type": "integer"
            },
            "formula": {
              "description": "A formula field's expression.",
              "type": "string"
            },
            "id": {
              "description": "The field's local projection address (fieldId).",
              "type": "integer"
            },
            "is_primary": {
              "description": "It names the record.",
              "type": "boolean"
            },
            "meta": {
              "additionalProperties": true,
              "description": "Metadata the host keeps with the field.",
              "type": "object"
            },
            "name": {
              "description": "The key of its values in a record's `values`.",
              "type": "string"
            },
            "options": {
              "additionalProperties": true,
              "description": "The settings its type reads (choices, target_table_id, …).",
              "type": "object"
            },
            "order": {
              "description": "Its position among the table's fields, from 1.",
              "type": "integer"
            },
            "readonly": {
              "description": "Values are not written by hand (formula and AI fields).",
              "type": "boolean"
            },
            "required": {
              "description": "A record needs a value.",
              "type": "boolean"
            },
            "table_id": {
              "description": "The table's id.",
              "type": "integer"
            },
            "title": {
              "description": "The title people see.",
              "type": "string"
            },
            "tool_id": {
              "description": "The stable UUID accepted by fieldId and used by receipts and conflicts.",
              "type": "string"
            },
            "type": {
              "description": "The field type.",
              "enum": [
                "text",
                "long_text",
                "number",
                "date",
                "datetime",
                "single_select",
                "multi_select",
                "checkbox",
                "url",
                "attachment",
                "document_link",
                "formula",
                "ai",
                "rating",
                "user",
                "link_to_record",
                "lookup",
                "rollup",
                "button",
                "created_time",
                "last_modified_time",
                "created_by",
                "last_modified_by",
                "auto_number"
              ],
              "type": "string"
            },
            "unique": {
              "description": "Values must differ between records.",
              "type": "boolean"
            },
            "updated_at": {
              "description": "When it last changed, in Unix milliseconds.",
              "type": "integer"
            },
            "user_id": {
              "description": "Always 0: the document's own user.",
              "type": "integer"
            }
          },
          "type": "object"
        },
        "items": {
          "items": {
            "additionalProperties": true,
            "description": "A record written.",
            "properties": {
              "record": {
                "additionalProperties": true,
                "description": "A record (row).",
                "properties": {
                  "created_at": {
                    "description": "When it was created, in Unix milliseconds.",
                    "type": "integer"
                  },
                  "document_id": {
                    "description": "Always 1: the document's id.",
                    "type": "integer"
                  },
                  "id": {
                    "description": "The record's local projection address (recordId).",
                    "type": "integer"
                  },
                  "order": {
                    "description": "Its position in the table, from 1.",
                    "type": "integer"
                  },
                  "row_key": {
                    "description": "The record's stable key, used by links, bulk commands and transact.",
                    "type": "string"
                  },
                  "table_id": {
                    "description": "The table's id.",
                    "type": "integer"
                  },
                  "tool_id": {
                    "description": "The stable UUID accepted by recordId and used by receipts and conflicts.",
                    "type": "string"
                  },
                  "updated_at": {
                    "description": "When it last changed, in Unix milliseconds.",
                    "type": "integer"
                  },
                  "user_id": {
                    "description": "Always 0: the document's own user.",
                    "type": "integer"
                  },
                  "values": {
                    "additionalProperties": true,
                    "description": "Its values, keyed by field name; a missing key is an empty value.",
                    "type": "object"
                  }
                },
                "type": "object"
              },
              "state": {
                "additionalProperties": true,
                "description": "The AI cell's run state.",
                "properties": {
                  "config_hash": {
                    "description": "A hash of the field's AI configuration.",
                    "type": "string"
                  },
                  "error": {
                    "description": "Empty, or why it failed.",
                    "type": "string"
                  },
                  "model_id": {
                    "description": "Always 0.",
                    "type": "integer"
                  },
                  "source_hash": {
                    "description": "A hash of what the model read.",
                    "type": "string"
                  },
                  "status": {
                    "description": "done.",
                    "type": "string"
                  },
                  "updated_at": {
                    "description": "When it was written, in Unix milliseconds.",
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "limit": {
          "description": "The most records one batch takes.",
          "type": "integer"
        },
        "record": {
          "additionalProperties": true,
          "description": "A record (row).",
          "properties": {
            "created_at": {
              "description": "When it was created, in Unix milliseconds.",
              "type": "integer"
            },
            "document_id": {
              "description": "Always 1: the document's id.",
              "type": "integer"
            },
            "id": {
              "description": "The record's local projection address (recordId).",
              "type": "integer"
            },
            "order": {
              "description": "Its position in the table, from 1.",
              "type": "integer"
            },
            "row_key": {
              "description": "The record's stable key, used by links, bulk commands and transact.",
              "type": "string"
            },
            "table_id": {
              "description": "The table's id.",
              "type": "integer"
            },
            "tool_id": {
              "description": "The stable UUID accepted by recordId and used by receipts and conflicts.",
              "type": "string"
            },
            "updated_at": {
              "description": "When it last changed, in Unix milliseconds.",
              "type": "integer"
            },
            "user_id": {
              "description": "Always 0: the document's own user.",
              "type": "integer"
            },
            "values": {
              "additionalProperties": true,
              "description": "Its values, keyed by field name; a missing key is an empty value.",
              "type": "object"
            }
          },
          "type": "object"
        },
        "state": {
          "additionalProperties": true,
          "description": "The AI cell's run state.",
          "properties": {
            "config_hash": {
              "description": "A hash of the field's AI configuration.",
              "type": "string"
            },
            "error": {
              "description": "Empty, or why it failed.",
              "type": "string"
            },
            "model_id": {
              "description": "Always 0.",
              "type": "integer"
            },
            "source_hash": {
              "description": "A hash of what the model read.",
              "type": "string"
            },
            "status": {
              "description": "done.",
              "type": "string"
            },
            "updated_at": {
              "description": "When it was written, in Unix milliseconds.",
              "type": "integer"
            }
          },
          "type": "object"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
```

## Parameter schema

```json
{
  "additionalProperties": false,
  "properties": {
    "action": {
      "description": "The AI action (summarize, translate, extract, improve, customize, classify, text_generation, image_generation, image_customization); when given, it must be the field's own.",
      "type": "string"
    },
    "asOrigin": {
      "description": "system:<name> writes as a host feature, outside the undo history. Agents leave it out.",
      "type": "string"
    },
    "config": {
      "additionalProperties": true,
      "description": "Overrides of the field's AI configuration for this run.",
      "type": "object"
    },
    "fieldId": {
      "description": "The AI field's id.",
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "string"
        }
      ],
      "x-khp-types": [
        "Field"
      ]
    },
    "recordId": {
      "description": "One record to run on.",
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "string"
        }
      ],
      "x-khp-types": [
        "Record"
      ]
    },
    "results": {
      "description": "What the host generated, one entry per record.",
      "items": {
        "additionalProperties": true,
        "properties": {
          "error": {
            "description": "Why generation failed for this record.",
            "type": "string"
          },
          "image": {
            "description": "A generated image."
          },
          "images": {
            "items": {},
            "type": "array"
          },
          "recordId": {
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ],
            "x-khp-role": "object",
            "x-khp-types": [
              "Record"
            ]
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "recordId"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "tableId": {
      "description": "The table's id.",
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "string"
        }
      ],
      "x-khp-types": [
        "Table"
      ]
    }
  },
  "required": [
    "tableId",
    "fieldId",
    "results"
  ],
  "type": "object"
}
```

Generated from kition-sdk packages/script/kits/table.ts and the kit itself (kition-table@ee73209).
