---
canonical_url: "https://docs.composio.dev/toolkits/past_dev"
markdown_url: "https://docs.composio.dev/toolkits/past_dev.md"
product: "platform"
version: null
last_updated: null
---

# Past.dev

Past.dev provides durable, source-backed memory for AI agents, including ingestion and its estimation and diagnostics, recall, identities, audiences, usage, request logs, memory traces, and explicit cleanup.

- **Category:** ai agents
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 29
- **Triggers:** 0
- **Slug:** `PAST_DEV`
- **Version:** 00000000_00

## Tools

### Replace Identities in Bulk

**Slug:** `PAST_DEV_BULK_REPLACE_IDENTITIES`

Atomically create or replace complete trait sets for up to 1,000 identities; omitted traits replace the identity with no traits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `identities` | array | Yes | Identity replacements (1-1,000). If an identity repeats, its last row wins. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Audience

**Slug:** `PAST_DEV_DELETE_AUDIENCE`

DESTRUCTIVE ACCESS CHANGE: Permanently delete an audience. Its stored memory remains but becomes permanently unreachable. The default project audience cannot be deleted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Non-default audience slug to permanently delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Identity

**Slug:** `PAST_DEV_DELETE_IDENTITY`

DESTRUCTIVE: Permanently delete an identity directory record and remove it from every audience. Stored memory associated with the identity remains and is not deleted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `identity` | string | Yes | Identity id whose directory record and audience memberships will be permanently removed. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Permanently Delete Ingestion Memory

**Slug:** `PAST_DEV_DELETE_INGESTION_MEMORY`

DESTRUCTIVE: Permanently delete every data point accepted by one ingestion and memory depending only on those points. This cannot be undone; the ingestion status and audit record remains readable.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ingestion_id` | string | Yes | Ingestion UUID whose accepted data points and derived memory will be permanently deleted. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Memory Data Point

**Slug:** `PAST_DEV_DELETE_MEMORY_DATA_POINT`

DESTRUCTIVE: Permanently delete one data point by its caller-owned source id and remove memory derived from it. This cannot be undone; the purge completes asynchronously.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_id` | string | Yes | Caller-owned source id of the data point and derived memory to permanently delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Memory Data Points

**Slug:** `PAST_DEV_DELETE_MEMORY_DATA_POINTS`

DESTRUCTIVE: Permanently and atomically delete up to 1,000 data points by caller-owned source id and remove memory derived from them. This cannot be undone; the purge completes asynchronously.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_ids` | array | Yes | Caller-owned source IDs to delete atomically. Duplicates count once; if any ID does not exist, nothing is deleted. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Estimate Ingestion

**Slug:** `PAST_DEV_ESTIMATE_INGESTION`

Cut files into data points, plan batches, and estimate credits without storing data or spending credits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `files` | array | No | Files for Past.dev to cut into points; provide files or items, not both. |
| `items` | array | No | Pre-cut data points to batch and price; provide items or files, not both. |
| `points` | string ("none" | "summary" | "full") | No | How much detail to return for each estimated data point. |
| `time_zone` | string | No | IANA time-zone name for file times without an explicit zone; defaults to UTC. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Explain Ingestion

**Slug:** `PAST_DEV_EXPLAIN_INGESTION`

Diagnose how far one send progressed, including per-item searchability, memory counts, failure details, and the recommended next step.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ingestion_id` | string | Yes | Ingestion ID returned by an ingest action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Find Trace Roots

**Slug:** `PAST_DEV_FIND_TRACE_ROOTS`

Find memory and source nodes for lineage or timeline inspection, returning independent memory and source cursors.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `first` | integer | No | Maximum entries per group (1-50). |
| `search` | string | No | Text, data point ID, or memory ID to find. |
| `ingestion_id` | string | No | Restrict both groups to nodes associated with this ingestion. |
| `after_sources` | string | No | Sources end_cursor from the previous call, passed back unchanged. |
| `after_memories` | string | No | Memories end_cursor from the previous call, passed back unchanged. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Audience

**Slug:** `PAST_DEV_GET_AUDIENCE`

Read one fixed, rule, or default audience with its definition and current membership and memory counts.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Audience slug, 2-40 lowercase letters, digits, or dashes, beginning and ending with a letter or digit. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Identity

**Slug:** `PAST_DEV_GET_IDENTITY`

Return one identity's traits, origin, timestamps, and current audience memberships.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `identity` | string | Yes | Identity id to retrieve, from 1 to 200 characters. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Ingestion Status

**Slug:** `PAST_DEV_GET_INGESTION_STATUS`

Poll one ingestion for processing, completion, failure, and project readiness without consuming metered request quota.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ingestion_id` | string | Yes | Ingestion ID returned by an ingest action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get API Request

**Slug:** `PAST_DEV_GET_REQUEST`

Read one API call and its retained allowlisted headers and request/response payload; bearer credentials are never returned.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | Request ID from LIST_REQUESTS or an X-Request-Id response header. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Request Histogram

**Slug:** `PAST_DEV_GET_REQUEST_HISTOGRAM`

Count accepted, failed-later, and rejected API calls in provider-selected time buckets using request-log filters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Match a request ID, API key name, or data point ID. |
| `to_time` | string | No | End of the request window; defaults to the current time. |
| `statuses` | array | No | Exact HTTP status codes to keep; each value is sent as status. |
| `endpoints` | array | No | Routed endpoint paths to keep; each value is sent as endpoint. |
| `from_time` | string | No | Start of the request window; defaults to 24 hours before to_time. |
| `key_names` | array | No | API key display names to keep; each value is sent as keyName. |
| `status_classes` | array | No | HTTP status classes to keep; each value is sent as statusClass. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Trace Lineage

**Slug:** `PAST_DEV_GET_TRACE_LINEAGE`

Read what a memory or source was built from and what was built on it, including graph edges and hidden-node count.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum nodes to return (1-400). |
| `reveal` | array | No | Repeatable node sides to open, each formatted as a UUID followed by :inputs or :outputs. |
| `root_id` | string | Yes | Internal memory or source UUID to use as the lineage root. |
| `reveal_all` | boolean | No | Walk every side of every node up to limit when true. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Trace Node

**Slug:** `PAST_DEV_GET_TRACE_NODE`

Read one memory or source node with revision, validity, replacement, request, content, and graph counts.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Internal memory or source UUID from another trace response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Trace Timeline

**Slug:** `PAST_DEV_GET_TRACE_TIMELINE`

Read rooted source and memory work, ingestions, recalls, and supersessions on a clock for a window of at most 31 days.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `root_id` | string | Yes | Internal memory or source UUID to use as the timeline root. |
| `to_time` | string | No | End of the timeline window. |
| `from_time` | string | No | Start of the timeline window; omit to use the root's recent history. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Usage

**Slug:** `PAST_DEV_GET_USAGE`

Return the current UTC month's credit balance, metering state, and project ingestion, recall, and cap usage.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Ingest Memory

**Slug:** `PAST_DEV_INGEST_MEMORY`

Ingest one timestamped data point into durable memory, optionally associating it with an identity and audience; reusing an id replaces the prior revision when stored fields change.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `label` | string | No | Human-readable source label returned with recall evidence. |
| `content` | string | Yes | Content to store as one memory data point. |
| `audience` | string | No | Audience slug allowed to recall this data point. |
| `identity` | string | No | Identity id, at most 200 characters, associated with this data point. |
| `metadata` | string | No | Any JSON metadata to preserve and return with source evidence. |
| `source_id` | string | No | Stable caller-owned id without '/'; reuse it to replace this data point's prior revision. |
| `timestamp` | string | No | When the content occurred; omit to use the provider's default time. |
| `idempotency_key` | string | No | Stable key, at most 200 characters, for safely retrying the same ingest request. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Ingest Memory Batch

**Slug:** `PAST_DEV_INGEST_MEMORY_BATCH`

Atomically ingest 1 to 1,000 ordered memory data points in one request, avoiding fragile per-item agent loops.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `items` | array | Yes | Ordered data points to ingest atomically (1-1,000). Each source ID may appear only once in the batch. |
| `idempotency_key` | string | No | Stable key, at most 200 characters, for safely retrying this entire atomic batch. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Audiences

**Slug:** `PAST_DEV_LIST_AUDIENCES`

List every audience in the connected project, including the default project audience and current membership and memory counts.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Identities

**Slug:** `PAST_DEV_LIST_IDENTITIES`

List project identities newest first, optionally filtering by one trait, and return a cursor for the next page.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum identities to return in this page (1-1000). |
| `trait_key` | string | No | Trait key to filter by; use with trait_value to match a specific value. |
| `next_cursor` | string | No | Opaque cursor returned as next_cursor by the previous page. Omit for the first page and pass it back unchanged to continue. |
| `trait_value` | string | No | Trait value to match for trait_key. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List API Requests

**Slug:** `PAST_DEV_LIST_REQUESTS`

List the connected project's API calls newest first, with filters and a cursor for the next page.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `first` | integer | No | Maximum request rows to return in this page (1-100). |
| `search` | string | No | Match a request ID, API key name, or data point ID. |
| `to_time` | string | No | End of the request window; defaults to the current time. |
| `statuses` | array | No | Exact HTTP status codes to keep; each value is sent as status. |
| `endpoints` | array | No | Routed endpoint paths to keep; each value is sent as endpoint. |
| `from_time` | string | No | Start of the request window; defaults to 24 hours before to_time. |
| `key_names` | array | No | API key display names to keep; each value is sent as keyName. |
| `next_cursor` | string | No | Cursor returned as next_cursor by the previous page. Omit for the first page and pass it back unchanged to continue. |
| `status_classes` | array | No | HTTP status classes to keep; each value is sent as statusClass. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Recall Memory

**Slug:** `PAST_DEV_RECALL_MEMORY`

Return ranked, source-backed memory visible to an identity for a query, with optional time range, sort order, and evidence budget controls.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sort` | string ("relevance" | "chronological") | No | Order results by relevance or occurrence time. |
| `level` | string ("low" | "medium" | "high" | "extra-high") | No | Preset evidence depth; do not combine with max_tokens. |
| `limit` | integer | No | Maximum ranked results to return from this bounded response (1-200). |
| `query` | string | Yes | Natural-language memory query, up to 1,000 characters. |
| `identity` | string | Yes | Identity id whose audience visibility controls the results, up to 200 characters. |
| `max_tokens` | integer | No | Positive custom evidence-token budget; do not combine with level. |
| `occurred_to` | string | No | Only consider evidence occurring at or before this time. |
| `occurred_from` | string | No | Only consider evidence occurring at or after this time. |
| `query_timestamp` | string | No | Time perspective from which to answer the query; omit to use the current time. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Recompute Audience

**Slug:** `PAST_DEV_RECOMPUTE_AUDIENCE`

Recompute an audience's membership from its definition and apply the refreshed access set to recall immediately.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Audience slug whose membership and recall access should be refreshed. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create or Replace Audience

**Slug:** `PAST_DEV_REPLACE_AUDIENCE`

Create or completely replace a fixed-list or trait-rule audience and its access definition. The default project audience cannot be replaced.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `kind` | string ("fixed" | "rule") | Yes | Definition kind: fixed identity list or trait rule. |
| `name` | string | No | Display name from 1 to 200 characters; defaults to the slug on create. |
| `rule` | object | No | Complete trait rule required for kind=rule. |
| `slug` | string | Yes | Non-default audience slug, 2-40 lowercase letters, digits, or dashes, beginning and ending with a letter or digit. |
| `identities` | array | No | Complete identity list for kind=fixed. This field is required for fixed, but an empty list is valid and reaches nobody. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Replace Identity

**Slug:** `PAST_DEV_REPLACE_IDENTITY`

Create an identity or replace its complete trait set; omitted or empty traits remove all existing traits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `traits` | object | No | Complete replacement trait map. Omitted or empty removes every existing trait; unspecified traits are not preserved. |
| `identity` | string | Yes | Identity id to create or replace, at most 200 characters. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retry Ingestion

**Slug:** `PAST_DEV_RETRY_INGESTION`

Retry a stopped or failed ingestion under its existing id without spending additional credits; completed ingestions are rejected.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ingestion_id` | string | Yes | Stopped or failed ingestion id to queue again. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Identity Traits

**Slug:** `PAST_DEV_UPDATE_IDENTITY_TRAITS`

Merge selected identity traits while preserving unspecified keys; set a trait value to null to remove that key.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `traits` | object | Yes | Trait changes to merge. Keys are 1 to 200 characters; string values are 1 to 2,000 characters; null removes a key. Past.dev requires this field even though its API reference marks it optional. |
| `identity` | string | Yes | Identity id whose traits should be updated, from 1 to 200 characters. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |