> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# What are Records?

Records store structured data that your Flows and Agents can use as context. Use Records for customer data, product catalogs, knowledge bases, and other application data.

## How Records work

Use Records to provide context for relevant, personalized responses. Common use cases include:

* **Knowledge bases**: Store documentation, FAQs, or product details for Agents to use in responses.
* **Customer profiles**: Store preferences, history, and account details for personalized interactions.
* **Product catalogs**: Store inventory, specifications, and prices for Flows to reference or update.
* **Conversation history**: Store chat logs and summaries for continuity across sessions.
* **Semantic search and retrieval-augmented generation (RAG)**: Find relevant Records by meaning and pass their content to prompts.

## Record structure

Each Record contains these parts:

* `type`: A category that groups related Records, such as `customers`, `products`, and `docs`.
* `name`: A name that is unique within the Record type, up to 500 characters. Use `type` and `name` together to look up a Record.
* `metadata`: A JSON object that stores your application data.
* `messages`: An optional list of chat messages, each with a `user` or `assistant` role, stored with the Record.
* `ownerId`: An optional key that identifies whose data the Record holds, such as your application's user ID. Use it to filter Records for one end user.
* `id`: A unique identifier that Runtype generates.
* `createdAt` and `updatedAt`: Timestamps that Runtype sets.

A Record with the same `type` and `name` as an existing Record is rejected with a duplicate error. To change an existing Record, update it, or use a Flow step or Agent tool that creates or updates a Record.

For example, the following Record stores customer data for Dana:

```json
{
  "id": "record_01jq8z6k2re9v0w1m3n5p7s9t2",
  "name": "Dana",
  "type": "customers",
  "metadata": {
    "email": "dana@example.com",
    "tier": "premium",
    "total_orders": 47,
    "last_purchase": "2026-01-10"
  }
}
```

### Owner key

Set `ownerId` when you create or update a Record through the API or a conversation, or in the dispatch `record` input. Send `ownerId: null` on an update to remove the owner. To find one end user's Records, filter by `ownerId` in the API or in a `recordFilter`. In a Flow, read the owner key with `{{_record.ownerId}}`.

Runtype does not use the owner key to control access. Your application must still check which end user can see which Records.

> **Note**
>
> `ownerId` is a reserved metadata key. If you send a string `metadata.ownerId`, Runtype stores it as the top-level `ownerId` field and returns it there, not in `metadata`. A top-level `ownerId` takes precedence over `metadata.ownerId`.

### Limits

Every Record write must stay within these limits:

* **`metadata` size**: 256 KB, measured as JSON.
* **Top-level `metadata` keys**: 200.
* **Length of a top-level `metadata` key**: 64 characters, after key normalization.
* **`metadata` nesting depth**: 5 levels.
* **`messages` entries**: 10,000.
* **Content of one message**: 1 MB.
* **Content of all messages**: 32 MB.

An API write that exceeds a limit fails with the error `record_payload_too_large`. The error details name the field and a code such as `METADATA_TOO_DEEP` or `MESSAGES_TOO_LARGE`.

## Flexible metadata

Store metadata as a JSON object. Use key-value pairs, nested objects, arrays, or combinations of these structures.

Use this metadata object when a product Record needs nested specifications and tags:

```json
{
  "product_id": "product-alpha",
  "name": "Product Alpha",
  "price": 99.99,
  "specs": {
    "weight": "2.5 kg",
    "dimensions": "10 x 5 x 3 cm"
  },
  "tags": ["electronics", "popular"]
}
```

When you create, update, or import Records in the dashboard, through the API, or with Agent tools, Runtype converts each top-level metadata key to lowercase snake_case. It keeps each original key as a label for the dashboard and CSV exports. For example:

* A CSV column named `Company Name` is stored as `company_name` and displays as **Company Name**.
* A key named `customerName` is stored as `customername`, because Runtype does not split camelCase words.

Use snake_case keys, such as `total_orders`, so the keys you send match the keys you read in Flows and filters.

> **Note**
>
> The **Upsert Record** Flow step stores metadata keys exactly as you send them. If a Flow writes `totalOrders` and the dashboard writes `total_orders`, the Record ends up with two different keys. Use snake_case keys in Flows too.

## Record types

Use the `type` field to group related Records. For example:

* `customers`: Customer profiles and preferences.
* `orders`: Order and transaction data.
* `docs`: Documentation articles.
* `faqs`: Frequently asked questions.

Use Record type views on the **Records** page to find Records of one type. Each Record type can use its own metadata structure.

To validate metadata for a Record type, register a collection with a JSON Schema and a validation mode of `off`, `warn`, or `enforce`. In `enforce` mode, writes whose metadata does not match the schema fail. For more information, see [Defining a schema](/user-guide/records/defining-a-schema).

## Ways to create Records

Create Records in these ways:

* **Templates**: Choose a pre-built structure such as Customer, Lead, Product, or Order.
* **CSV import**: Upload a CSV file to create Records in bulk.
* **Flow steps**: Use the [`upsert-record` step](/user-guide/flows/using-record-steps-upsert-retrieve) to create or update Records in a Flow.
* **Agent tools**: Give an Agent the Record Management [built-in tools](/user-guide/tools/built-in-tools), such as **Upsert Record**, **Get Record**, and **List Records**, so it can read and write Records.
* **API**: Send `POST /v1/records`. For request details, see the [Create record API reference](/api-reference/runtype-api/records/create-record).
* **CLI**: Run `runtype records create`.
* **Runtype MCP server**: Use Record tools such as `create_record` and `list_records` from an AI client. For setup, see [Runtype MCP server](/developer-guides/integrations/runtype-mcp-server).

## Manage Records in the dashboard

The **Records** page includes these controls and views:

* **Search**: Find Records by name or type.
* **Record type views**: Filter Records by Record type.
* **Metadata preview**: Show up to three metadata keys as badges.
* **Bulk edit** and **Delete**: Update metadata or remove multiple Records.
* **Details**: View system fields, metadata, and labels in the details panel.
* **Messages**: View messages stored on the Record.
* **Results**: View the Record's execution history.
* **Activity**: View changes made to the Record.
* **Run**: Run a Flow with a Record as input.
* **Export**: Download filtered Records as a CSV file.

## Semantic search

To add semantic search, create embeddings for Record content with the **Generate Embedding** step. Save the embeddings to a connected vector store with the **Store Vector** step. Query the stored embeddings with the **Vector Search** step. For step details, see [Flow step types overview](/user-guide/flows/flow-step-types-overview).

Use a query such as *affordable laptops for students*. **Vector Search** can return Records about budget-friendly computers, even when those exact words do not appear in the content.

## Record usage tips

Use these practices to keep Record data consistent:

* **Use meaningful Record types**: Choose consistent names so you can filter Records predictably.
* **Start with a template**: Choose a template with fields that match your Record type.
* **Use readable column names in CSV imports**: Runtype keeps the original column names as labels in the dashboard and CSV exports.
* **Use Flows**: Create or update Records from external data sources.

## Next steps

Continue with these pages:

* [Creating and managing records](/user-guide/records/creating-and-managing-records): create, import, edit, and delete Records.
* [Defining a schema](/user-guide/records/defining-a-schema): validate metadata for a Record type.
* [Using records in flows](/user-guide/records/using-records-in-flows): retrieve and update Records in Flows.
* [Using record steps](/user-guide/flows/using-record-steps-upsert-retrieve): configure the Flow steps that read and write Records.
* [Filtering and searching records](/user-guide/records/filtering-and-searching-records): filter Records and configure semantic search.
* [Building retrieval that works](/user-guide/records/building-retrieval-that-works): design Records and queries for reliable retrieval.
* [Managing records programmatically](/user-guide/records/managing-records-programmatically): create, edit, export, and import Records with the API, SDK, CLI, and MCP.