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:

  • name: A display label that identifies the Record. The value can contain up to 500 characters.
  • type: A category that groups related Records, such as customers, products, and docs.
  • metadata: A JSON object that stores your application data.
  • id: A unique identifier that Runtype generates.
  • ownerId: An optional owner key identifying whose data the Record is, for example your application’s own user ID. Set it on POST/PUT /v1/records, POST/PUT /v1/conversations, or the dispatch record input; send ownerId: null on an update to clear it. Filter with ?ownerId= on GET /v1/records, GET /v1/records/export, and GET /v1/conversations, use ownerId as a top-level field in a recordFilter, and read it in flows as {{_record.ownerId}}.

The owner key partitions data inside your own multi-tenant app. It is builder-managed and carries no authorization semantics — it does not replace end-user identity scoping.

For example, use Dana’s customer data in a Record with this structure:

1{
2  "id": "record_01jq8z6k2re9v0w1m3n5p7s9t2",
3  "name": "Dana",
4  "type": "customers",
5  "metadata": {
6    "email": "dana@example.com",
7    "tier": "premium",
8    "totalOrders": 47,
9    "lastPurchase": "2026-01-10"
10  }
11}

Use flexible metadata

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

ownerId is a reserved metadata key on record, conversation, and dispatch writes. When a string metadata.ownerId is sent, Runtype stores the value in the Record’s first-class ownerId field instead of metadata, and responses return it as top-level ownerId, never as metadata.ownerId. A top-level ownerId overrides a nested one, an explicit metadata.ownerId: null clears the owner, and other non-string values under metadata.ownerId are kept as ordinary metadata.

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

1{
2  "productId": "product-alpha",
3  "name": "Product Alpha",
4  "price": 99.99,
5  "specs": {
6    "weight": "2.5 kg",
7    "dimensions": "10 x 5 x 3 cm"
8  },
9  "tags": ["electronics", "popular"]
10}

Runtype normalizes metadata keys when you create or import Records. It stores the original keys as metadata labels, so the dashboard and CSV exports can show readable names. For example, company_name can display as Company Name in the dashboard.

Record types

Use the type field to group related Records into collections. 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 a collection. Each Record type can use its own metadata structure.

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.
  • API: Use the Runtype API to create and manage Records programmatically.

Manage Records in the dashboard

The Records page includes these controls and views:

  • Search: Find Records by name or metadata.
  • 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.
  • Add metadata labels: Show readable names in the dashboard and CSV headers.
  • Use Flows: Create or update Records from external data sources.

Next steps

Continue with these pages: