Skip to content
My Docs My Docs letta-sdk
  • Auto
  • Light
  • Dark
DiscordForumGitHubSign up
API Reference
Blocks
View as Markdown
Copy Markdown
Open in Claude
Open in ChatGPT

List Blocks

blocks.list(BlockListParams**kwargs) -> SyncArrayPage[BlockResponse]
get/v1/blocks/

List Blocks

ParametersExpand Collapse
after: Optional[str]

Block ID cursor for pagination. Returns blocks that come after this block ID in the specified sort order

before: Optional[str]

Block ID cursor for pagination. Returns blocks that come before this block ID in the specified sort order

connected_to_agents_count_eq: Optional[Iterable[int]]

Filter blocks by the exact number of connected agents. If provided, returns blocks that have exactly this number of connected agents.

connected_to_agents_count_gt: Optional[int]

Filter blocks by the number of connected agents. If provided, returns blocks that have more than this number of connected agents.

connected_to_agents_count_lt: Optional[int]

Filter blocks by the number of connected agents. If provided, returns blocks that have less than this number of connected agents.

Search blocks by description. If provided, returns blocks that match this description. This is a full-text search on block descriptions.

identifier_keys: Optional[SequenceNotStr[str]]

Search agents by identifier keys

identity_id: Optional[str]

Search agents by identifier id

label: Optional[str]

Labels to include (e.g. human, persona)

Search blocks by label. If provided, returns blocks that match this label. This is a full-text search on labels.

limit: Optional[int]

Number of blocks to return

name: Optional[str]

Name of the block

order: Optional[Literal["asc", "desc"]]

Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest first

Accepts one of the following:
"asc"
"desc"
order_by: Optional[Literal["created_at"]]

Field to sort by

Accepts one of the following:
"created_at"
project_id: Optional[str]

Search blocks by project id

templates_only: Optional[bool]

Whether to include only templates

Search blocks by value. If provided, returns blocks that match this value.

ReturnsExpand Collapse
class BlockResponse: …
id: str

The id of the block.

value: str

Value of the block.

Deprecatedbase_template_id: Optional[str]

(Deprecated) The base template id of the block.

created_by_id: Optional[str]

The id of the user that made this Block.

Deprecateddeployment_id: Optional[str]

(Deprecated) The id of the deployment.

description: Optional[str]

Description of the block.

Deprecatedentity_id: Optional[str]

(Deprecated) The id of the entity within the template.

Deprecatedhidden: Optional[bool]

(Deprecated) If set to True, the block will be hidden.

is_template: Optional[bool]

Whether the block is a template (e.g. saved human/persona options).

label: Optional[str]

Label of the block (e.g. 'human', 'persona') in the context window.

last_updated_by_id: Optional[str]

The id of the user that last updated this Block.

limit: Optional[int]

Character limit of the block.

metadata: Optional[Dict[str, object]]

Metadata of the block.

Deprecatedpreserve_on_migration: Optional[bool]

(Deprecated) Preserve the block on template migration.

project_id: Optional[str]

The associated project id.

Deprecatedread_only: Optional[bool]

(Deprecated) Whether the agent has read-only access to the block.

Deprecatedtemplate_id: Optional[str]

(Deprecated) The id of the template.

Deprecatedtemplate_name: Optional[str]

(Deprecated) The name of the block template (if it is a template).

List Blocks
  • HTTP
  • TypeScript
  • Python
from letta_client import Letta

client = Letta(
    api_key="My API Key",
)
page = client.blocks.list()
page = page.items[0]
print(page.id)
[
  {
    "id": "id",
    "value": "value",
    "base_template_id": "base_template_id",
    "created_by_id": "created_by_id",
    "deployment_id": "deployment_id",
    "description": "description",
    "entity_id": "entity_id",
    "hidden": true,
    "is_template": true,
    "label": "label",
    "last_updated_by_id": "last_updated_by_id",
    "limit": 0,
    "metadata": {
      "foo": "bar"
    },
    "preserve_on_migration": true,
    "project_id": "project_id",
    "read_only": true,
    "template_id": "template_id",
    "template_name": "template_name"
  }
]
Returns Examples
[
  {
    "id": "id",
    "value": "value",
    "base_template_id": "base_template_id",
    "created_by_id": "created_by_id",
    "deployment_id": "deployment_id",
    "description": "description",
    "entity_id": "entity_id",
    "hidden": true,
    "is_template": true,
    "label": "label",
    "last_updated_by_id": "last_updated_by_id",
    "limit": 0,
    "metadata": {
      "foo": "bar"
    },
    "preserve_on_migration": true,
    "project_id": "project_id",
    "read_only": true,
    "template_id": "template_id",
    "template_name": "template_name"
  }
]