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

# POMA Grill

POMA Grill is a project-scoped context engine for ingesting documents, managing indexed content, and retrieving prompt-ready context for LLM applications.

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

## Tools

### Cancel Bucket Ingest Task

**Slug:** `POMA_GRILL_CANCEL_BUCKET_INGEST_TASK`

Irreversibly cancel a non-terminal POMA Grill bucket-ingest task. Already terminal tasks cannot be cancelled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Bucket-ingest task UUID returned by Submit Bucket Ingest. |

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

### Cancel Ingest Job

**Slug:** `POMA_GRILL_CANCEL_INGEST_JOB`

Request best-effort cancellation and removal of an ingestion job. A successful response does not guarantee that completed job metadata disappears.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | Exact ingestion job UUID to cancel or remove. |

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

**Slug:** `POMA_GRILL_DELETE_DOCUMENT`

Permanently delete one deliberately selected indexed document, including its vectors and stored assets. This action cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document_id` | string | Yes | Exact document UUID to permanently remove; obtain and verify it with List Documents or Get Document first. |

#### 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 Bucket Ingest Task

**Slug:** `POMA_GRILL_GET_BUCKET_INGEST_TASK`

Get the current state, progress, processing rate, credential status, and recent failures for a POMA Grill bucket-ingest task.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Bucket-ingest task UUID returned by Submit Bucket Ingest. |

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

**Slug:** `POMA_GRILL_GET_DOCUMENT`

Get metadata for one indexed document by its document ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document_id` | string | Yes | Document UUID returned by ingestion, search, or List Documents. |

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

**Slug:** `POMA_GRILL_GET_INGEST_JOB`

Get an ingestion job's current status and usage; poll this after Ingest Document until status is done, failed, or blocked. Grill jobs may pass through indexing before reaching a terminal state.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | Ingestion job UUID returned by Ingest Document. |

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

**Slug:** `POMA_GRILL_INGEST_DOCUMENT`

Upload one file or provide one public remote URL for asynchronous indexing, and return the ingestion job ID to poll with Get Ingest Job.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | No | File content to upload and index; the single-upload body limit is 50 MB. Provide exactly one of file or remote_url. |
| `labels` | array | No | Optional labels to attach for later filtering; at most 64 labels, 128 characters each, and 4096 serialized characters total. |
| `attributes` | object | No | Typed document attributes. Names must be lowercase letters, digits, or underscores and at most 64 characters; serialized JSON is capped at 2048 characters. |
| `meta_int_1` | integer | No | Deprecated customer integer metadata for range queries. |
| `meta_int_2` | integer | No | Deprecated customer integer metadata for range queries. |
| `remote_url` | string | No | Publicly accessible URL for POMA to fetch instead of uploading a file. Provide exactly one of remote_url or file. |
| `canonical_url` | string | No | Citation URL associated with the ingested document. |
| `attribute_schema` | object | No | Types for newly introduced attributes, required for datetime and encrypted_text values. Serialized JSON is capped at 2048 characters. |
| `unencrypted_strings` | object | No | Plaintext string metadata for glob filtering; at most 32 keys and 16384 serialized characters. Keys use letters, digits, or underscores. |

#### 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 Bucket Ingest Failures

**Slug:** `POMA_GRILL_LIST_BUCKET_INGEST_FAILURES`

Return one page of failed items for a bucket ingest task, ordered by item ID, with an opaque cursor for the next page.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum failed items to return in this page (1-1000). |
| `cursor` | string | No | Opaque continuation cursor returned by the previous call. Omit it for the first page and pass it back unchanged for the next page. |
| `task_id` | string | Yes | Bucket-ingest task UUID returned by Submit Bucket Ingest. |

#### 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:** `POMA_GRILL_LIST_DOCUMENTS`

List one page of document metadata from the connected project.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum documents to return on this page; omit for legacy list behavior. |
| `cursor` | string | No | Opaque pagination cursor from a previous response; pass it unchanged and omit it for the first page. |

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

### Pause Bucket Ingest Task

**Slug:** `POMA_GRILL_PAUSE_BUCKET_INGEST_TASK`

Pause a non-terminal bucket ingest task in paused_user state. Processing halts on the next scheduler tick while the task continues to occupy its account's active-task slot.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Bucket-ingest task UUID returned by Submit Bucket Ingest. |

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

### Preview Bucket Ingest

**Slug:** `POMA_GRILL_PREVIEW_BUCKET_INGEST`

Validate S3 or GCS credentials and preview matching source objects without creating a bucket-ingest task. Sensitive credentials are sent to POMA and exposed to the action execution environment.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | object | Yes | Source bucket and the credentials POMA uses to list and read it. |
| `destination` | object | No | Optional customer-owned destination for processed results; omit to keep results only in POMA-managed storage. |
| `filter_glob` | string | No | Optional object-key glob such as "*.pdf"; nonmatching files are skipped. |
| `acknowledge_egress_cost` | boolean | No | Set true to acknowledge estimated egress cost when the provider requires confirmation for a destination transfer. |

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

### Resume Bucket Ingest Task

**Slug:** `POMA_GRILL_RESUME_BUCKET_INGEST_TASK`

Resume a bucket ingest task paused by the user, restoring its pre-pause state and waking processing for the next scheduler tick.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Bucket-ingest task UUID returned by Submit Bucket Ingest. |

#### 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 Bucket Ingest Failures

**Slug:** `POMA_GRILL_RETRY_BUCKET_INGEST_FAILURES`

Retry all or selected failed items in a bucket ingest task that is in done_with_errors or materialising. Refresh purged source credentials first.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Bucket-ingest task UUID returned by Submit Bucket Ingest. |
| `item_ids` | array | No | Failed item UUIDs to retry. Omit or pass an empty list to retry every failed item in the task. |

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

**Slug:** `POMA_GRILL_SEARCH_DOCUMENTS`

Search indexed content across the project or within one document, returning either prompt-ready context or structured matching chunks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural-language or keyword query to retrieve relevant indexed content. |
| `format` | string ("prompt_ready" | "json") | No | Response form: prompt_ready for assembled context or json for structured chunks and relevance scores. |
| `doc_ids` | array | No | Restrict search to at most 100 document IDs. |
| `premium` | boolean | No | Enable premium retrieval features such as reranking. |
| `labels_all` | array | No | Deprecated alias for meta_tags_all. |
| `labels_any` | array | No | Deprecated alias for meta_tags_any. |
| `max_tokens` | integer | No | Hard maximum context size in estimated tokens (100-500000). When below target_tokens, POMA clamps the soft target down to this ceiling. |
| `document_id` | string | No | Optional document UUID. When set, search only that document; otherwise search the full project namespace. |
| `meta_tags_all` | array | No | Deprecated label filter requiring all listed metadata tags. |
| `meta_tags_any` | array | No | Deprecated label filter requiring any listed metadata tag. |
| `min_relevance` | number | No | Optional minimum relevance threshold from 0 to 1 for returned matches. |
| `return_assets` | boolean | No | Return extracted figures and tables referenced by included documents. |
| `target_tokens` | integer | No | Preferred context size in estimated tokens (100-500000). |
| `meta_int_1_gte` | integer | No | Deprecated inclusive lower bound for metadata integer field 1. |
| `meta_int_1_lte` | integer | No | Deprecated inclusive upper bound for metadata integer field 1. |
| `meta_int_2_gte` | integer | No | Deprecated inclusive lower bound for metadata integer field 2. |
| `meta_int_2_lte` | integer | No | Deprecated inclusive upper bound for metadata integer field 2. |
| `retrieval_tier` | string | No | Retrieval tier override, such as free, standard, or premium. |
| `exclude_doc_ids` | array | No | Exclude at most 100 document IDs from search results. |
| `expand_tightness` | number | No | Controls how aggressively context is expanded around hits, from 0 to 1. |
| `attribute_filters` | array | No | Up to 32 typed attribute clauses, combined with AND. |
| `min_top_relevance` | number | No | Return no results when the top result scores below this 0-1 threshold. |
| `unencrypted_strings_match` | object | No | Ingest-time unencrypted string keys mapped to case-insensitive Unix glob patterns. |

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

### Submit Bucket Ingest

**Slug:** `POMA_GRILL_SUBMIT_BUCKET_INGEST`

Create an asynchronous task to ingest matching objects from an S3 or GCS bucket into POMA Grill, optionally delivering results to another bucket. Source and destination credentials are sensitive inputs sent to POMA and exposed to the action execution environment.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | object | Yes | Source bucket and the credentials POMA uses to list and read it. |
| `destination` | object | No | Optional customer-owned destination for processed results; omit to keep results only in POMA-managed storage. |
| `filter_glob` | string | No | Optional object-key glob such as "*.pdf"; nonmatching files are skipped. |
| `acknowledge_egress_cost` | boolean | No | Set true to acknowledge estimated egress cost when the provider requires confirmation for a destination transfer. |

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

### Submit Bucket Ingest Eco (Legacy)

**Slug:** `POMA_GRILL_SUBMIT_BUCKET_INGEST_ECO_LEGACY`

Deprecated compatibility route for creating a POMA Grill bucket-ingest task. Use Submit Bucket Ingest for new calls; POMA documents both routes as behaviorally identical.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | object | Yes | Source bucket and the credentials POMA uses to list and read it. |
| `destination` | object | No | Optional customer-owned destination for processed results; omit to keep results only in POMA-managed storage. |
| `filter_glob` | string | No | Optional object-key glob such as "*.pdf"; nonmatching files are skipped. |
| `acknowledge_egress_cost` | boolean | No | Set true to acknowledge estimated egress cost when the provider requires confirmation for a destination transfer. |

#### 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 Bucket Ingest Credentials

**Slug:** `POMA_GRILL_UPDATE_BUCKET_INGEST_CREDENTIALS`

Replace and validate the source credentials for an active bucket ingest task. A task paused for a source credential error resumes materialising on success.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Bucket-ingest task UUID returned by Submit Bucket Ingest. |
| `source_bucket_access` | object | Yes | Replacement sensitive access details for the task's source bucket. POMA validates and stores them encrypted for this task. |

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

**Slug:** `POMA_GRILL_UPDATE_DOCUMENT_ATTRIBUTES`

Set, change, or remove selected typed attributes on one indexed document. Null attribute values remove those attributes; omitted names are unchanged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `attributes` | object | Yes | Attribute names to set, update, or remove. A null value removes that attribute; omitted names remain unchanged. |
| `document_id` | string | Yes | Document identifier returned by ingestion, search, or List Documents. |
| `attribute_schema` | object | No | Types for attributes first introduced to the namespace. Required for datetime and encrypted_text values; declare only names in attributes. |

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