Skip to navigation
Records

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:

{
  "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.

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:

{
  "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.

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.

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 to create or update Records in a Flow.
  • Agent tools: Give an Agent the Record Management 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.
  • 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.

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.

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.

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: