State Management

State is persistent key-value storage that works across all your Triggers, Steps, and Functions. Set data in one Trigger, read it in another. Works across TypeScript, Python, and JavaScript.

How It Works

State organizes data into groups. Each group can hold multiple items with unique keys.

Think of it like folders and files:

groupId = A folder name (like orders, users, cache)
key = A file name inside that folder
value = The actual data

import { type Handlers, type StepConfig } from 'motia'
 
export const config = {
  name: 'MyStep',
  description: 'Demonstrates state usage',
  triggers: [
    { type: 'queue', topic: 'my-topic' },
  ],
  flows: ['my-flow'],
} as const satisfies StepConfig
 
export const handler: Handlers<typeof config> = async (input, { state }) => {
  // Store an item in a group (returns { new_value, old_value })
  const result = await state.set('orders', 'order-123', {
    id: 'order-123',
    status: 'pending',
    total: 99.99
  })
 
  // Get a specific item
  const order = await state.get('orders', 'order-123')
 
  // Get all items in a group
  const allOrders = await state.list('orders')
 
  // Delete a specific item
  await state.delete('orders', 'order-123')
 
  // Clear entire group
  await state.clear('orders')
}

State Methods

Method	What it does
`state.set(groupId, key, value)`	Store an item in a group. Returns `StreamSetResult` with `new_value` and `old_value`
`state.get(groupId, key)`	Get a specific item (returns `null` if not found)
`state.list(groupId)`	Get all items in a group as an array
`state.delete(groupId, key)`	Remove a specific item
`state.clear(groupId)`	Remove all items in a group
`state.update(groupId, key, ops)`	Atomic update with `UpdateOp[]`

Atomic Updates

The update() method performs atomic operations on state data, eliminating race conditions from manual get-then-set patterns.

Use update() instead of getting a value, modifying it, and setting it back. Atomic updates prevent data loss when multiple Steps modify the same state concurrently.

TypeScript/JavaScript

await ctx.state.update('orders', orderId, [
  { type: 'increment', path: 'completedSteps', by: 1 },
  { type: 'set', path: 'status', value: 'shipped' },
  { type: 'decrement', path: 'retries', by: 1 },
])

Python

await context.state.update("orders", order_id, [
    {"type": "increment", "path": "completedSteps", "by": 1},
    {"type": "set", "path": "status", "value": "shipped"},
    {"type": "decrement", "path": "retries", "by": 1},
])

UpdateOp Types

Type	Fields	Description
`set`	`path`, `value`	Set a field to a value (overwrite)
`merge`	`path` (optional), `value`	Merge an object into the existing value
`increment`	`path`, `by`	Increment a numeric field
`decrement`	`path`, `by`	Decrement a numeric field
`remove`	`path`	Remove a field entirely

update() returns { new_value, old_value } just like set().

Learn more about Atomic Updates

Real-World Example

Let's build an order processing workflow that uses state across multiple Steps.

Step 1 - API receives order:

import { type Handlers, type StepConfig } from 'motia'
 
export const config = {
  name: 'CreateOrder',
  description: 'Receive and store a new order',
  triggers: [
    { type: 'http', path: '/orders', method: 'POST' },
  ],
  enqueues: ['order.created'],
  flows: ['order-processing'],
} as const satisfies StepConfig
 
export const handler: Handlers<typeof config> = async (req, { state, enqueue, logger }) => {
  const orderId = crypto.randomUUID()
 
  const order = {
    id: orderId,
    items: req.body.items,
    total: req.body.total,
    status: 'pending',
    createdAt: new Date().toISOString()
  }
 
  // Store in state
  await state.set('orders', orderId, order)
 
  logger.info('Order created', { orderId })
 
  // Trigger processing
  await enqueue({
    topic: 'order.created',
    data: { orderId }
  })
 
  return { status: 201, body: order }
}

Step 2 - Process payment:

import { type Handlers, type StepConfig } from 'motia'
 
export const config = {
name: 'ProcessPayment',
description: 'Process payment for an order',
triggers: [
  { type: 'queue', topic: 'order.created' },
],
enqueues: ['payment.completed'],
flows: ['order-processing'],
} as const satisfies StepConfig
 
export const handler: Handlers<typeof config> = async (input, { state, enqueue, logger }) => {
const { orderId } = input
 
// Get order from state
const order = await state.get('orders', orderId)
 
if (!order) {
  throw new Error(`Order ${orderId} not found`)
}
 
// Update status
order.status = 'paid'
await state.set('orders', orderId, order)
 
logger.info('Payment processed', { orderId })
 
await enqueue({
  topic: 'payment.completed',
  data: { orderId }
})
}

Step 3 - View all orders (Cron job):

import { type Handlers, type StepConfig, cron } from 'motia'
 
export const config = {
name: 'DailyReport',
description: 'Generate daily order report',
triggers: [
  cron('0 0 * * *'),
],
enqueues: [],
flows: ['order-processing'],
} as const satisfies StepConfig
 
export const handler: Handlers<typeof config> = async (input, { state, logger }) => {
// Get all orders
const allOrders = await state.list<Order>('orders')
 
const pending = allOrders.filter(o => o.status === 'pending')
const paid = allOrders.filter(o => o.status === 'paid')
 
logger.info('Daily order report', {
  total: allOrders.length,
  pending: pending.length,
  paid: paid.length
})
}

When to Use State

Good use cases:

Temporary workflow data - Data that's only needed during a flow execution
API response caching - Cache expensive API calls that don't change often
Sharing data between Steps - Pass data between Steps without enqueuing it in events
Building up results - Accumulate data across multiple Steps

Better alternatives:

Persistent user data - Use a database like Postgres or MongoDB
File storage - Use S3 or similar for images, PDFs, documents
Real-time updates - Use Motia Streams for live data to clients
Large datasets - Use a proper database, not state

Inspecting State in the iii Console

The iii development console lets you browse, inspect, and manage state groups and individual entries in real-time:

State inspector in the iii Console

Remember

Organize data using groupId (like orders, users, cache)
Each item needs a unique key within its groupId
Use list(groupId) to retrieve all items in a group
state.set() returns { new_value, old_value } (StreamSetResult)
Use state.update() for atomic operations like increment/decrement
State works the same across TypeScript, Python, and JavaScript
Clean up state when you're done with it
Use databases for permanent data, state for temporary workflow data

Steps can react to state changes automatically using state triggers. This enables powerful reactive patterns — for example, triggering a step when a parallel merge completes, without polling or manual coordination.

export const config = {
  name: 'OnTaskComplete',
  triggers: [
    {
      type: 'state',
      condition: (input) => {
        if (!input.new_value) return false
        return input.group_id === 'tasks' && input.new_value.completedSteps === input.new_value.totalSteps
      },
    },
  ],
  flows: ['task-flow'],
} as const satisfies StepConfig

Learn more about State Triggers

On this page