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

# BrainGraph

BrainGraph builds a searchable knowledge graph from documents, recordings, web pages, and other source material for grounded AI workflows.

- **Category:** artificial intelligence
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 10
- **Triggers:** 0
- **Slug:** `BRAIN_GRAPH`
- **Version:** 00000000_00

## Tools

### Get Document Progress

**Slug:** `BRAIN_GRAPH_GET_DOCUMENT_PROGRESS`

Get the current transcription, processing, and analysis status for a BrainGraph document. Poll until transcript.status is analyzed; analysis is null while processing is incomplete.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document_id` | integer | Yes | Document ID returned by a BrainGraph upload or ingestion tool. |

#### 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 Web Page

**Slug:** `BRAIN_GRAPH_INGEST_WEB_PAGE`

Fetch readable content from a public web page and queue it for BrainGraph ingestion. This creates persistent data and consumes upload and URL-submission quota. After a timeout or other ambiguous failure, check for the document before retrying to avoid a duplicate and additional quota use.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | Public HTTP(S) web-page URL to fetch. BrainGraph rejects private, loopback, and metadata-service addresses, including after redirects. |
| `notes` | string | No | Optional context to guide extraction and later retrieval. |
| `conversation_date` | string | No | ISO 8601 date associated with the page content. |

#### 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 YouTube Video

**Slug:** `BRAIN_GRAPH_INGEST_YOUTUBE_VIDEO`

Submit a YouTube video for metadata, transcript, and speaker processing; the result may only confirm that processing was queued. This creates persistent data and consumes upload and URL-submission quota. After a timeout or incomplete stream, check for the document before retrying to avoid a duplicate and additional quota use.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | YouTube watch, Shorts, embed, live, or youtu.be URL. |
| `language` | string | No | Optional two-letter caption-track language code, such as en or es. |

#### 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 Brains

**Slug:** `BRAIN_GRAPH_LIST_BRAINS`

List the connected BrainGraph account's knowledge brains and identify the default brain for filtering or targeting other tools.

#### 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 Documents

**Slug:** `BRAIN_GRAPH_LIST_DOCUMENTS`

List BrainGraph documents newest first, optionally filtering by filename or notes, failed ingestion status, and brain. Returns one page at a time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum documents in this page (1-100). |
| `query` | string | No | Case-insensitive substring to match against document filenames and notes. |
| `cursor` | string | No | Opaque continuation cursor returned by a previous call; omit for the first page. |
| `brain_ids` | array | No | Brain IDs to include; omit to list documents across all brains. |
| `include_failed` | boolean | No | Include documents whose ingestion failed. |

#### 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 Graph Patterns

**Slug:** `BRAIN_GRAPH_LIST_PATTERNS`

Find recurring relationship-chain patterns in the connected BrainGraph knowledge graph, subject to a minimum occurrence count.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum patterns to return. BrainGraph does not provide a continuation mechanism for this endpoint. |
| `min_frequency` | integer | No | Minimum number of occurrences required for a recurring pattern. |

#### 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 |

### Resolve Entity

**Slug:** `BRAIN_GRAPH_RESOLVE_ENTITY`

Resolve an entity name to a canonical BrainGraph record. If there is no single match, return an explicit ambiguous or not-found result rather than treating it as an HTTP error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entity_name` | string | Yes | Entity name to resolve, such as a person, organization, project, or concept. |

#### 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 |

### Search Brain

**Slug:** `BRAIN_GRAPH_SEARCH_BRAIN`

Search facts in the connected account's BrainGraph knowledge graph using a natural-language question, optionally restricted to selected brains.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural-language question or topic to search for in the knowledge graph. |
| `brain_ids` | array | No | Brain IDs to search. Omit to search all brains; this selection is ignored on single-brain accounts. |
| `num_results` | integer | No | Maximum number of matching facts to return (1-50). |

#### 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 |

### Transcribe Audio

**Slug:** `BRAIN_GRAPH_TRANSCRIBE_AUDIO`

Upload an audio file or submit a direct public audio URL for diarized transcription and graph ingestion. This creates persistent data and consumes upload and transcription allowance. Do not retry automatically after an ambiguous failure because a retry can create a duplicate document.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | No | MP3, M4A, WAV, OGG, OGA, OPUS, WEBM, AAC, FLAC, or MP4 file supplied by the caller, up to approximately 150 MB. |
| `notes` | string | No | Optional transcription or extraction context. |
| `brain_id` | string | No | Target brain ID; omit for the default Personal Brain. |
| `filename` | string | No | Optional display filename for an uploaded file. |
| `audio_url` | string | No | Direct public HTTP(S) URL of an audio file, not a web player page. Provide exactly one of audio_url or file. |
| `conversation_date` | string | No | ISO 8601 date associated with the recording. |

#### 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 |

### Upload Document

**Slug:** `BRAIN_GRAPH_UPLOAD_DOCUMENT`

Upload a document file supplied by the caller or plain text and queue it for BrainGraph ingestion. This creates persistent data and consumes the account's upload allowance. After a timeout or other ambiguous failure, check for the document before retrying to avoid a duplicate and additional quota use.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | No | PDF, DOCX, PPTX, TXT, MD, HTML, or EML file supplied by the caller, up to approximately 35 MB. |
| `notes` | string | No | Optional context to guide extraction and later retrieval. |
| `content` | string | No | Plain-text content to ingest through the JSON endpoint. Provide exactly one of content or file. |
| `brain_id` | string | No | Target brain ID; omit to use the default Personal Brain. |
| `filename` | string | No | Display filename. Required when content is provided and optional as an override when a file is provided. |
| `conversation_date` | string | No | ISO 8601 date associated with the document or conversation. |

#### 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 |