# Message Metadata



Attach user-defined metadata to any message regardless of format. Metadata is stored separately and can be retrieved or updated independently.

## Store Message with Metadata [#store-message-with-metadata]

<CodeGroup>
  ```python title="Python"
  client.sessions.store_message(
      session_id=session.id,
      blob={"role": "user", "content": "Hello!"},
      format="openai",
      meta={"source": "web", "request_id": "abc123", "user_agent": "mobile"}
  )
  ```

  ```typescript title="TypeScript"
  await client.sessions.storeMessage(
    session.id,
    { role: "user", content: "Hello!" },
    { format: "openai", meta: { source: "web", request_id: "abc123" } }
  );
  ```
</CodeGroup>

## Retrieve Metadata [#retrieve-metadata]

The `metas` array in `get_messages` response contains metadata for each message in the same order as `items` and `ids`.

<CodeGroup>
  ```python title="Python"
  result = client.sessions.get_messages(session_id=session.id, format="openai")

  for i, msg in enumerate(result.items):
      meta = result.metas[i]
      print(f"Message: {msg}, Meta: {meta}")
  ```

  ```typescript title="TypeScript"
  const result = await client.sessions.getMessages(session.id, { format: "openai" });

  for (let i = 0; i < result.items.length; i++) {
      const msg = result.items[i];
      const meta = result.metas[i];
      console.log(`Message: ${JSON.stringify(msg)}, Meta: ${JSON.stringify(meta)}`);
  }
  ```
</CodeGroup>

## Update Metadata [#update-metadata]

Use `patch_message_meta` to add, update, or delete metadata keys after message creation.

<CodeGroup>
  ```python title="Python"
  # Add or update keys
  updated = client.sessions.patch_message_meta(
      session_id=session.id,
      message_id=msg.id,
      meta={"status": "processed", "score": 0.95}
  )

  # Delete a key by passing None
  updated = client.sessions.patch_message_meta(
      session_id=session.id,
      message_id=msg.id,
      meta={"old_key": None}
  )
  ```

  ```typescript title="TypeScript"
  // Add or update keys
  const updated = await client.sessions.patchMessageMeta(
    session.id,
    msg.id,
    { status: "processed", score: 0.95 }
  );

  // Delete a key by passing null
  await client.sessions.patchMessageMeta(
    session.id,
    msg.id,
    { old_key: null }
  );
  ```
</CodeGroup>

## Next Steps [#next-steps]

<CardGroup cols="2">
  <Card title="Multi-provider Messages" icon="arrows-rotate" href="/store/messages/multi-provider">
    Store and convert between OpenAI, Anthropic, and Gemini formats
  </Card>

  <Card title="Anthropic Special Flags" icon="bolt" href="/store/messages/special/anthropic">
    Preserve Anthropic-specific flags like prompt caching
  </Card>
</CardGroup>