Skip to navigation
Records

Creating and managing records

Records store structured data that your Flows and Agents use. Create Records for customer profiles, product catalogs, support tickets, and other data. Each Record includes a name, type, metadata, and ID. For a conceptual overview, read What are Records?.

A Record type groups similar Records. Use types to filter the Records list and scope record lookups in Flows and Agents. Examples include Customer, Support Ticket, and Product Listing.

Create a Record

On the Records page, click Create Record and choose one of the following options:

  • Quick create: create a Record from scratch.
  • Use template: open Quick create with fields prefilled for a common use case.
  • Import CSV file: create multiple Records from a CSV file.

Each Record’s combination of type and name must be unique. Runtype rejects a Record that has the same type and name as an existing Record.

If the Record type has a schema in enforce mode, Runtype rejects metadata that doesn’t match the schema. In warn mode, Runtype saves the Record and marks it as not matching. For details, read Defining a schema for a record type.

Use Quick create

  1. On the Records page, click Create Record, then select Quick create.
  2. Enter a Name and Type. Both fields are required.
  3. To add metadata, click Add Field, then enter a key and value.
  4. To save the Record, click Create Record. To save it and open its details, click Create & Edit.

The Type field suggests types that already exist in your workspace. To create a type, enter a new name. Runtype adds it to the type options after the Record exists.

Add metadata fields

The Quick create form stores metadata values as text. For nested objects or arrays, use the Runtype API or an Upsert Record step in a Flow.

When you save a Record on the Records page, through the Runtype API, or from a CSV import, Runtype converts top-level metadata keys to lowercase snake_case. For example, Customer Name becomes customer_name, and customerName becomes customername. Use the stored key when you reference a field in a Flow.

The following JSON object shows metadata values that the form stores:

{
  "customer_name": "Jane Doe",
  "order_count": "47",
  "is_premium": "true"
}

Runtype rejects a write whose metadata exceeds one of the following limits:

  • 256 KB of metadata per Record
  • 200 top-level keys
  • 64 characters per key
  • 5 levels of nesting

Use a template

To start with predefined fields, select Use template. Runtype provides templates in the following categories:

  • Business: Customer, Lead, and Employee.
  • E-commerce: Product and Order.
  • Marketing: Marketing Campaign and Contact.
  • General: Project, Task, and Generic Record.

Select a template. The Quick create form opens with the name, type, and metadata fields prefilled. Update any field before you save.

Import Records from a CSV file

To create multiple Records, choose Import CSV file from Create Record. If the page has no Records, choose Import records in the empty state.

Your CSV file needs a header row and at least one data row. To start from a correctly formatted file, click Download Sample in the import dialog.

Follow these steps to upload the file:

  1. Upload the CSV file.
  2. Under Type, select a CSV column or enter one Record type to use for every row.
  3. Under Name Column, select the column that contains each Record’s name.
  4. Review the mapping preview, then click Upload.

Runtype preselects a Type column whose header contains type or category. It preselects a name column whose header contains name or title. Check these selections before you upload.

The importer uses the selected columns for each Record’s name and type. It also stores every CSV column as a metadata field, including the type and name columns. Column headers become lowercase snake_case keys.

The following CSV file creates two Records, each with type, name, email, and tier metadata fields:

type,name,email,tier
customer,Jane Doe,jane@example.com,premium
customer,John Smith,john@example.com,standard

An import can partly succeed. The notification after the upload reports how many Records Runtype created and how many rows failed. A row fails for any of the following reasons:

  • Its type or name is empty.
  • Its type and name match an existing Record or an earlier row in the file.
  • A column header converts to an empty or reserved key.
  • Its metadata exceeds a metadata limit.
  • Its metadata doesn’t match a Record type schema in enforce mode.

To check the result, select the view for the imported type. To import the rows that failed, fix them and upload a CSV file that contains only those rows.

Search, filter, and export Records

Use the Records table to find and export Records. The search field matches Record names and types.

The list view picker includes All records and one view for each available Record type. Select a view to limit the list to that type.

To download matching Records as a CSV file, click Export. Choose 25, 50, 100, or 250 Records per page. The default is 100.

Edit a Record

  1. Click a Record row or select View details from its row action menu.
  2. Click Edit.
  3. Update the Name, Type, or metadata fields.
  4. Click Save Changes.

The Messages tab holds conversation messages stored on the Record. To add or change messages, click Edit, then update them on the Messages tab. Use a Record with messages as input for batch Agent runs.

To reference a Record in a Flow or API request, select Copy record ID from its row action menu.

Bulk edit Records

To change metadata on multiple Records, select them in the table, then select Bulk edit.

Follow these steps to preview and apply a bulk edit:

  1. Choose an action under Action:
    • Update fields: change values in existing metadata fields.
    • Add fields: add metadata fields to the selected Records.
    • Delete fields: remove metadata fields from the selected Records.
  2. If you selected rows, choose a scope under Apply to. Selected records is the default. To target Records by type and metadata values, select Records matching a filter.
  3. Add the fields to update, add, or delete. Use dot notation for nested fields, such as address.city.
  4. Click Preview. The dialog shows the Records that the edit affects, and it does not change them yet.
  5. Click Apply Updates, Apply Additions, or Apply Deletions, depending on the action you chose. The edit changes only the Records included in the preview.

If you select Records matching a filter and leave Filter by (optional) empty, the edit targets every Record in your account. The dialog requires confirmation before it generates the preview.

If the edit makes any Record’s metadata violate its type’s schema in enforce mode, Runtype rejects the whole edit.

Bulk edit changes metadata only. To change a Record’s name or type, edit the Record individually.

Delete Records

To delete one Record, open its row action menu, select Delete, and confirm.

The Record leaves the list right away, and a notification offers Undo for 10 seconds. To keep the Record, click Undo within 10 seconds. If you dismiss the notification or leave the Records page, Runtype deletes the Record right away. If you close the tab during the undo window, refresh the list to check whether the Record was deleted.

To delete multiple Records, select them in the table, select Delete in the selection bar, and confirm. A bulk delete offers no Undo and takes effect right away.

A delete is permanent. A Get Record step that references a deleted Record reports Record not found.

Manage Records with the API or CLI

You can also create, update, and delete Records from code. The following request creates a Record:

curl --request POST https://api.runtype.com/v1/records \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "customer",
    "name": "Jane Doe",
    "metadata": { "email": "jane@example.com", "tier": "premium" }
  }'

Replace YOUR_API_KEY with your Runtype API key. The request returns 409 if a Record with the same type and name exists.

The following CLI command creates the same Record:

runtype records create -n "Jane Doe" -t customer -m '{"email":"jane@example.com","tier":"premium"}'

The CLI also includes the runtype records update, delete, bulk-edit, and bulk-delete commands. The API reference documents the Records endpoints for update, bulk edit, bulk delete, and CSV upload. For the request fields, see Create record.

View results and activity

Open a Record’s details sheet and click Results. Review each Flow run’s status, output, token usage, duration, and cost. Filter results by status or Flow, and choose a sort order.

Click Activity to review changes to the Record. Activity requires an Enterprise plan. On other plans, the tab shows an upgrade prompt. Activity shows who created, edited, or deleted the Record and includes before and after snapshots of its name and metadata. Bulk edits, bulk deletes, and CSV imports also appear. For audit details, read the Audit trail.

To run a Flow with a Record, open the row action menu and select Run. For instructions on building Flows, read Creating and editing flows.

Use Records in Flows

Use these Flow steps with Records:

  • Upsert Record: create or update a Record.
  • Update Record: change fields on an existing Record.
  • Get Record and List Records: retrieve one or more Records.
  • Generate Embedding, Store Vector, and Vector Search: create, store, and query embeddings for semantic search.

These steps let you populate metadata, retrieve context, and search Record content in a Flow. For step definitions, read Flow step types overview.

Best practices

Use these practices to keep Records consistent:

  • Use the same metadata field names within a Record type so Flows can reference them.
  • Choose descriptive type names, such as Customer Profile or Support Ticket, so filtering and Flow configuration stay clear.
  • Store only the data that your Flows and Agents use.

Next steps