Skip to main content
Filter sessions by their configs metadata using JSONB containment. Only sessions where configs contains all key-value pairs in your filter will be returned.

​
Basic Usage

import os
from acontext import AcontextClient

client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY"))

# Create sessions with configs
session1 = client.sessions.create(configs={"agent": "bot1", "env": "prod"})
session2 = client.sessions.create(configs={"agent": "bot2", "env": "dev"})

# Filter by single key
sessions = client.sessions.list(filter_by_configs={"agent": "bot1"})
# Returns: session1

​
Filter Examples

​
Multiple Keys

Sessions must match all key-value pairs: 
# Only returns sessions with BOTH agent="bot1" AND env="prod"
sessions = client.sessions.list(
    filter_by_configs={"agent": "bot1", "env": "prod"}
)

​
Nested Objects

Filter by nested config values: 
# Create session with nested config
session = client.sessions.create(
    configs={"agent": {"name": "bot1", "version": "2.0"}}
)

# Filter by nested object
sessions = client.sessions.list(
    filter_by_configs={"agent": {"name": "bot1"}}
)

​
Combine with User Filter

# Filter by both user and configs
sessions = client.sessions.list(
    user="[email protected]",
    filter_by_configs={"agent": "bot1"}
)

​
Important Behaviors

  • Case-sensitive: {"Agent": "x"} won’t match {"agent": "x"}
  • Type-sensitive: {"count": 1} won’t match {"count": "1"}
  • Partial matching: filter {"a": 1} matches configs {"a": 1, "b": 2}
  • NULL excluded: Sessions with configs=null are excluded from filtered results

​
Next Steps

Per-user Sessions

Associate sessions with users

Multi-provider Messages

Store messages in any format