Pulse

https://docs.runpulse.com
Admin
Pulse is a production-grade document extraction platform that transforms complex documents (PDFs,...
Tokens:191,230
Snippets:1,768
Trust Score:8.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Expose Local Server with ngrok

Source: https://docs.runpulse.com/svix-webhooks

Use these commands to start your local server and expose it to the internet for webhook testing. Replace the example URL with the one provided by ngrok in your terminal.

```bash
# Start your local server
python webhook_handler.py

# In another terminal, expose it to the internet
ngrok http 5000

# Use the ngrok URL in the webhook portal
# Example: https://abc123.ngrok.io/webhook
```

--------------------------------

### Install and initialize Pulse CLI

Source: https://docs.runpulse.com/cli/overview

Standard installation and initialization workflow for the Pulse CLI.

```bash
uv tool install pulse-ai-cli
pulse login
pulse extract report.pdf
```

--------------------------------

### Install Pulse CLI via uv

Source: https://docs.runpulse.com/cli/overview

Installation command using the uv tool.

```bash
uv tool install pulse-ai-cli
```

--------------------------------

### Install uv

Source: https://docs.runpulse.com/mcp/connecting

Install the uv tool manager on your system if it is not already installed.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Check uvx installation

Source: https://docs.runpulse.com/mcp/connecting

Verify that uvx is installed by checking its version.

```bash
uvx --version
```

--------------------------------

### CI Extraction Example

Source: https://docs.runpulse.com/cli/commands

Example of running an extraction in a CI environment, setting the API key and saving the JSON output to a file.

```bash
# CI example: fail the step if extraction fails, keep the artifact
export PULSE_API_KEY="$PULSE_KEY_FROM_SECRETS"
pulse extract spec.pdf --json > spec.pulse.json
```

--------------------------------

### Install Pulse SDKs

Source: https://docs.runpulse.com/api-reference/sdks

Commands to install the official Pulse SDKs for Python and TypeScript.

```bash
pip install pulse-python-sdk
```

```bash
npm install pulse-ts-sdk
```

--------------------------------

### Batch Schema Single Mode Examples

Source: https://docs.runpulse.com/api-reference/endpoint/batch-overview

Examples for initiating a batch schema job in single mode using Python, TypeScript, and cURL.

```python
from pulse.types.schema_config import SchemaConfig

resp = client.batch.schema(
    batch_extract_id="<batch_extract_job_id>",
    output=BatchOutputDestination(s_3_prefix="s3://my-bucket/results/schemas/"),
    schema_config=SchemaConfig(
        input_schema={
            "type": "object",
            "properties": {
                "total_amount": {"type": "number"},
                "vendor_name": {"type": "string"},
            },
        },
        schema_prompt="Extract invoice details",
    ),
    workers=10,
)
```

```typescript
const resp = await client.batch.schema({
    batchExtractId: "<batch_extract_job_id>",
    output: { s3_prefix: "s3://my-bucket/results/schemas/" },
    schemaConfig: {
        inputSchema: {
            type: "object",
            properties: {
                total_amount: { type: "number" },
                vendor_name: { type: "string" },
            },
        },
        schemaPrompt: "Extract invoice details",
    },
    workers: 10,
});
```

```bash
curl -X POST https://api.runpulse.com/batch/schema \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_extract_id": "<batch_extract_job_id>",
    "output": { "s3_prefix": "s3://my-bucket/results/schemas/" },
    "schema_config": {
      "input_schema": {
        "type": "object",
        "properties": {
          "total_amount": {"type": "number"},
          "vendor_name": {"type": "string"}
        }
      },
      "schema_prompt": "Extract invoice details"
    },
    "workers": 10
  }'
```

--------------------------------

### Install Pulse CLI via pip

Source: https://docs.runpulse.com/cli/overview

Installation command using pip. Requires Python 3.11+.

```bash
pip install pulse-ai-cli
```

--------------------------------

### Schema Configuration Example

Source: https://docs.runpulse.com/api-reference/structured-output-guidelines

A JSON configuration object defining the input schema and prompt for invoice extraction.

```json
{
  "extraction_id": "abc123-...",
  "schema_config": {
    "input_schema": {
      "type": "object",
      "properties": {
        "invoice_number": {
          "type": "string",
          "description": "The unique invoice identifier"
        },
        "total": {
          "type": "number",
          "description": "Total invoice amount"
        }
      },
      "required": ["invoice_number", "total"]
    },
    "schema_prompt": "Extract invoice details"
  }
}
```

--------------------------------

### Fill Form From URL

Source: https://docs.runpulse.com/api-reference/endpoint/form-fill

Examples for filling a PDF form using a publicly accessible URL.

```python
from pulse import Pulse

client = Pulse(api_key="YOUR_API_KEY")

result = client.form.fill(
    file_url="https://example.com/intake-form.pdf",
    instructions="Fill in patient name as Jane Doe, DOB 01/15/1990.",
)

print(f"form_id={result.form_id}")
print(f"fields_filled={result.fields_filled}")
print(f"credits_used={result.credits_used}")
print(f"download: {result.pdf_url}")
```

```typescript
import { PulseClient } from "pulse-ts-sdk";

const client = new PulseClient({ apiKey: "YOUR_API_KEY" });

const result = await client.form.fill({
    file_url: "https://example.com/intake-form.pdf",
    instructions: "Fill in patient name as Jane Doe, DOB 01/15/1990.",
});

console.log(`form_id=${result.form_id}`);
console.log(`fields_filled=${result.fields_filled}`);
console.log(`download: ${result.pdf_url}`);
```

```bash
curl -X POST https://api.runpulse.com/form/fill \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/intake-form.pdf",
    "instructions": "Fill in patient name as Jane Doe, DOB 01/15/1990."
  }'
```

--------------------------------

### Perform First Extraction Request

Source: https://docs.runpulse.com/api-reference/sdks

Example of extracting content from a PDF file using the Pulse client.

```python
from pulse import Pulse

client = Pulse(api_key="YOUR_API_KEY")

result = client.extract(
    file=open("document.pdf", "rb"),
)

print(result.extraction_id)
print(result.markdown)
```

```typescript
import { PulseClient } from "pulse-ts-sdk";
import * as fs from "fs";

const client = new PulseClient({ apiKey: "YOUR_API_KEY" });

const result = await client.extract({
  file: fs.createReadStream("document.pdf"),
});

console.log(result.extraction_id);
console.log(result.markdown);
```

--------------------------------

### Async Response JSON

Source: https://docs.runpulse.com/api-reference/endpoint/tables

Example of an asynchronous response indicating that table processing has started.

```json
{
  "tables_id": "uuid-123",
  "status": "pending",
  "message": "Table processing started. Poll GET /job/{tables_id} for results."
}
```

--------------------------------

### Complete Integration Example in Python

Source: https://docs.runpulse.com/svix-webhooks

Demonstrates the full workflow of configuring webhooks, submitting an async extraction, and defining a handler function to process the job completion in Python.

```python
from pulse import Pulse

client = Pulse(api_key="YOUR_API_KEY")

# One-time setup: Configure webhooks
portal_response = client.webhooks.create_webhook_link()
print(f"Configure webhooks at: {portal_response.link}")
print("Add your webhook endpoint URL in the portal")

# Define extraction schema
schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string"},
        "sections": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "heading": {"type": "string"},
                    "content": {"type": "string"}
                }
            }
        }
    }
}

# Submit async extraction - webhook will notify when complete
submission = client.extract(
    file_url="https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
    pages="1-100",
    async_=True
)

# After extraction completes (via webhook), apply schema via /schema endpoint:
# schema_result = client.schema(
#     extraction_id=submission.extraction_id,
#     schema_config={"input_schema": schema}
# )

print(f"Extraction started: {submission.job_id}")
print("You'll receive a webhook notification when complete!")

# When webhook fires, fetch the results
def handle_webhook_completion(job_id: str):
    """Called when webhook notification is received."""
    job_status = client.jobs.get_job(job_id=job_id)
    
    if job_status.status == "completed":
        print(f"Job {job_id} completed!")
        print(f"Result: {job_status.result}")
    else:
        print(f"Job {job_id} status: {job_status.status}")
```

--------------------------------

### Poll for Job Status via cURL

Source: https://docs.runpulse.com/api-reference/async-processing

Example of checking the job status using a standard HTTP GET request.

```bash
# Poll for status
curl "https://api.runpulse.com/job/abc123-def456" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Initialize Pulse Client and Extract Document

Source: https://docs.runpulse.com/authentication

Examples for initializing the client and performing a document extraction using the official SDKs or a direct curl request.

```python
from pulse import Pulse

# Initialize the client with your API key
client = Pulse(api_key="YOUR_API_KEY")

# Extract a document
response = client.extract(
    file_url="https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf"
)

print(f"Extraction ID: {response.extraction_id}")
print(f"Markdown: {response.markdown[:200]}...")
```

```typescript
import { PulseClient } from 'pulse-ts-sdk';

// Initialize the client with your API key
const client = new PulseClient({ 
    apiKey: 'YOUR_API_KEY'
});

// Extract a document
const response = await client.extract({
    fileUrl: "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf"
});

console.log(`Extraction ID: ${response.extraction_id}`);
console.log(`Markdown: ${response.markdown?.substring(0, 200)}...`);
```

```bash
curl -X POST https://api.runpulse.com/extract \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@document.pdf"
```

--------------------------------

### Complete Integration Example in TypeScript

Source: https://docs.runpulse.com/svix-webhooks

Demonstrates the full workflow of configuring webhooks, submitting an async extraction, and defining a handler function to process the job completion in TypeScript.

```typescript
import { PulseClient } from 'pulse-ts-sdk';

const client = new PulseClient({ 
    apiKey: 'YOUR_API_KEY'
});

// One-time setup: Configure webhooks
const portalResponse = await client.webhooks.createWebhookLink();
console.log(`Configure webhooks at: ${portalResponse.link}`);
console.log("Add your webhook endpoint URL in the portal");

// Define extraction schema
const schema = {
    type: "object",
    properties: {
        title: { type: "string" },
        sections: {
            type: "array",
            items: {
                type: "object",
                properties: {
                    heading: { type: "string" },
                    content: { type: "string" }
                }
            }
        }
    }
};

// Submit async extraction - webhook will notify when complete
const submission = await client.extract({
    fileUrl: "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
    pages: "1-100",
    async: true
});

// After extraction completes (via webhook), apply schema:
// const schemaResult = await client.schema({
//     extractionId: submission.extraction_id,
//     schemaConfig: { schema }
// });

console.log(`Extraction started: ${submission.job_id}`);
console.log("You'll receive a webhook notification when complete!");

// When webhook fires, fetch the results
async function handleWebhookCompletion(jobId: string) {
    const jobStatus = await client.jobs.getJob({ jobId });
    
    if (jobStatus.status === "completed") {
        console.log(`Job ${jobId} completed!`);
        console.log(`Result: ${JSON.stringify(jobStatus.result)}`);
    } else {
        console.log(`Job ${jobId} status: ${jobStatus.status}`);
    }
}
```

--------------------------------

### Full Pipeline Example in Python

Source: https://docs.runpulse.com/api-reference/endpoint/batch-overview

A complete workflow for processing SEC filings, including extraction, schema application, table extraction, splitting by topic, and per-topic schema application.

```python
from pulse import Pulse
from pulse.types.batch_input_source import BatchInputSource
from pulse.types.batch_output_destination import BatchOutputDestination
from pulse.types.schema_config import SchemaConfig
from pulse.types.split_config import SplitConfig
from pulse.types.tables_config import TablesConfig
from pulse.types.topic_definition import TopicDefinition
from pulse.types.topic_schema_config import TopicSchemaConfig
import time

client = Pulse(api_key="YOUR_API_KEY")

def wait_for_job(job_id: str) -> dict:
    while True:
        job = client.jobs.get_job(job_id=job_id)
        if job.status in ("completed", "failed", "canceled"):
            return {"status": job.status, "result": job.result}
        time.sleep(5)

# Step 1: Batch Extract
extract = client.batch.extract(
    input=BatchInputSource(s_3_prefix="s3://my-bucket/10-K/"),
    output=BatchOutputDestination(s_3_prefix="s3://my-bucket/results/extractions/"),
    workers=10,
)
extract_result = wait_for_job(extract.batch_job_id)

# Step 2: Batch Schema
schema = client.batch.schema(
    batch_extract_id=extract.batch_job_id,
    output=BatchOutputDestination(s_3_prefix="s3://my-bucket/results/schemas/"),
    schema_config=SchemaConfig(
        input_schema={"type": "object", "properties": {"revenue": {"type": "number"}}},
    ),
    workers=10,
)
wait_for_job(schema.batch_job_id)

# Step 3: Batch Tables
tables = client.batch.tables(
    batch_extract_id=extract.batch_job_id,
    output=BatchOutputDestination(s_3_prefix="s3://my-bucket/results/tables/"),
    tables_config=TablesConfig(merge=True, table_format="html"),
    workers=10,
)
wait_for_job(tables.batch_job_id)

# Step 4: Batch Split
split = client.batch.split(
    batch_extract_id=extract.batch_job_id,
    output=BatchOutputDestination(s_3_prefix="s3://my-bucket/results/splits/"),
    split_config=SplitConfig(split_input=[
        TopicDefinition(name="financials", description="Financial statements"),
        TopicDefinition(name="risk_factors", description="Risk disclosures"),
    ]),
    workers=10,
)
wait_for_job(split.batch_job_id)

# Step 5: Batch Schema (split mode)
split_schema = client.batch.schema(
    batch_split_id=split.batch_job_id,
    output=BatchOutputDestination(s_3_prefix="s3://my-bucket/results/schema-splits/"),
    split_schema_config={
        "financials": TopicSchemaConfig(
            schema_={"type": "object", "properties": {"revenue": {"type": "number"}}},
        ),
        "risk_factors": TopicSchemaConfig(
            schema_={"type": "object", "properties": {"risks": {"type": "array", "items": {"type": "string"}}}},
        ),
    },
    workers=10,
)
wait_for_job(split_schema.batch_job_id)
```

--------------------------------

### Catch-all Classification Example

Source: https://docs.runpulse.com/api-reference/endpoint/classify

An example of defining a catch-all classification by omitting the pipeline_id, which serves as an escape hatch for documents that do not match specific categories.

```jsonc
{
  "classifications": {
    "bank_statement": {
      "description": "Bank or account statements: balances, transaction lists, deposits and withdrawals.",
      "pipeline_id": "b1a2c3d4-..."
    },
    "invoice": {
      "description": "Invoices or bills requesting payment: line items, amounts due, payment terms.",
      "pipeline_id": "e5f6a7b8-..."
    },
    "unrecognized": {
      // No pipeline_id — so classify_output.pipeline_id comes back null
      "description": "Any document that does not clearly match one of the other classifications — including unrelated document types, blank or illegible scans, and standalone cover pages."
    }
  }
}
```

--------------------------------

### Partial Results Response Example

Source: https://docs.runpulse.com/api-reference/endpoint/extract

Example of a JSON response containing a failed_pages entry, indicating that specific pages could not be extracted while others succeeded.

```json
{
  "markdown": "...\n<!-- PAGE 7153 FAILED EXTRACTION: content could not be certified -->\n...",
  "page_count": 11622,
  "failed_pages": [
    {"page": 7153, "error": "content could not be certified"}
  ],
  "warnings": [
    "1 of 11622 pages could not be certified; see failed_pages"
  ]
}
```

--------------------------------

### Configure Tempo wallet for an agent

Source: https://docs.runpulse.com/advanced/mpp-payments

Commands to teach an agent the Tempo wallet or expose it via an MCP server.

```bash
# Teach your agent the Tempo wallet (Claude Code shown; works the same for other agents)
claude -p "Read https://tempo.xyz/SKILL.md and set up tempo"

# Or expose the wallet to your agent as an MCP server
tempo wallet mcp add --agent claude-code
```

--------------------------------

### Sync FormResult Response Example

Source: https://docs.runpulse.com/api-reference/endpoint/form-fill

Example of a successful synchronous Form Fill response containing PDF details, filled fields, and billing information.

```json
{
  "form_id": "00e2c454-4e6f-429b-bd74-320ad94b2153",
  "page_count": 6,
  "pdf_url": "https://api.runpulse.com/results/dab7285d-8a65-4cb6-9d24-d5db64d3798e/pdf",
  "form_fields": [
    {
      "page_number": 1,
      "type": "text",
      "bounding_box": [0.118, 0.226, 0.634, 0.241],
      "text": "Acme Logistics LLC"
    },
    {
      "page_number": 1,
      "type": "checkbox",
      "bounding_box": [0.118, 0.226, 0.634, 0.241],
      "text": "Individual/sole proprietor C corporation S corporation Partnership",
      "checkbox_details": [
        { "center_coord": [0.125, 0.232], "selected": true,  "text": "Individual/sole proprietor" },
        { "center_coord": [0.300, 0.232], "selected": false, "text": "C corporation" },
        { "center_coord": [0.418, 0.232], "selected": false, "text": "S corporation" },
        { "center_coord": [0.535, 0.232], "selected": false, "text": "Partnership" }
      ]
    }
  ],
  "fields_filled": 7,
  "credits_used": 18.0,
  "plan_info": {
    "tier": "trial",
    "total_credits_used": 1284.0,
    "pages_used": 428
  }
}
```

--------------------------------

### Core Processing with cURL

Source: https://docs.runpulse.com/api-reference/endpoint/extract

Demonstrates using refinement parameters like refine, refine_prompt, and detect_selections to steer the extraction process.

```bash
curl -X POST https://api.runpulse.com/extract \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/bank-statement.pdf",
    "additional_prompt": "Preserve account labels and signed amounts.",
    "refine": {
      "modes": ["tables", "text"],
      "prompt": "Keep source row and column order."
    },
    "detect_selections": true,
    "figure_processing": {
      "description": true
    },
    "custom_image_prompt": "Describe axes, units, and legends."
  }'
```

--------------------------------

### Complete Processing Example JSON

Source: https://docs.runpulse.com/api-reference/endpoint/extract

A comprehensive example of the JSON payload used to configure document extraction, including file URL, refinement modes, figure processing, and chunking extensions.

```json
{
  "file_url": "https://example.com/document.pdf",
  "async": true,
  "additional_prompt": "Preserve account labels and signed amounts.",
  "refine": {
    "modes": ["tables", "text"],
    "prompt": "Keep the source row and column order."
  },
  "detect_selections": true,
  "figure_processing": {
    "description": true,
    "show_images": true
  },
  "custom_image_prompt": "Describe axes, units, and legends.",
  "extensions": {
    "chunking": {
      "chunk_types": ["semantic", "page"],
      "chunk_size": 1000
    },
    "document_metadata": true
  }
}
```

--------------------------------

### Initialize Pulse Client

Source: https://docs.runpulse.com/api-reference/sdks

Initialize the Pulse client using an API key from environment variables.

```python
import os
from pulse import Pulse

client = Pulse(api_key=os.environ["PULSE_API_KEY"])
```

```typescript
import { PulseClient } from "pulse-ts-sdk";

const client = new PulseClient({
  apiKey: process.env.PULSE_API_KEY!,
});
```

--------------------------------

### POST /webhook

Source: https://docs.runpulse.com/api-reference/introduction

Get portal link to configure webhook endpoints.

```APIDOC
## POST /webhook

### Description
Get portal link to configure webhook endpoints.

### Method
POST

### Endpoint
/webhook
```

--------------------------------

### Extract, Split, and Schema in Python

Source: https://docs.runpulse.com/platform-reference/extract-split-schema

Demonstrates the full workflow using the Python SDK, including extraction, splitting by topic, and applying specific schemas to each topic.

```python
from pulse import Pulse

client = Pulse(api_key="YOUR_API_KEY")

# Step 1: Extract
extract_result = client.extract(
    file=open("annual_report.pdf", "rb"),
    async_=True,
    storage={"enabled": True}
)
extraction_id = extract_result.extraction_id

# Step 2: Split
split_result = client.split(
    extraction_id=extraction_id,
    split_config={
        "split_input": [
            {"name": "Financials", "description": "Revenue, expenses, and profit data"},
            {"name": "Leadership", "description": "Executive team and board members"},
            {"name": "Outlook", "description": "Future plans and projections"}
        ]
    }
)
split_id = split_result.split_id
print(f"Split: {split_result.split_output}")

# Step 3: Schema per topic
schema_result = client.schema(
    split_id=split_id,
    split_schema_config={
        "Financials": {
            "schema": {
                "type": "object",
                "properties": {
                    "total_revenue": {"type": "number"},
                    "net_income": {"type": "number"}
                }
            },
            "schema_prompt": "Extract financial metrics"
        },
        "Leadership": {
            "schema": {
                "type": "object",
                "properties": {
                    "ceo": {"type": "string"},
                    "board_members": {"type": "array", "items": {"type": "string"}}
                }
            },
            "schema_prompt": "Extract leadership information"
        },
        "Outlook": {
            "schema": {
                "type": "object",
                "properties": {
                    "guidance": {"type": "string"},
                    "growth_target": {"type": "number"}
                }
            },
            "schema_prompt": "Extract forward-looking statements"
        }
    }
)

for topic, data in schema_result.results.items():
    print(f"{topic}: {data}")
```

--------------------------------

### GET /poll

Source: https://docs.runpulse.com/api-reference/endpoint/poll

Check the status and retrieve results of an asynchronous job.

```APIDOC
## GET /poll

### Description
Check the status and retrieve results of an asynchronous job (submitted via any endpoint with `async: true`). Poll this endpoint periodically until the job reaches a terminal state (`completed`, `failed`, `canceled`, or `expired`).

### Method
GET

### Endpoint
/poll

### Response
#### Success Response (200)
- **job_id** (string) - Unique identifier for the extraction job.
- **status** (string) - Current job status: `pending`, `processing`, `completed`, `failed`, `canceled`, or `expired`.
- **created_at** (string) - ISO 8601 timestamp when the job was submitted.
- **updated_at** (string) - ISO 8601 timestamp of the last status update.
- **result** (object) - Job output. Present when `status` is `completed`, and on `expired` as a retention stub.
- **result.failed_pages** (array) - Only present on partial results. Lists pages that could not be extracted.
- **error** (string) - Error message (only present when `status` is `failed`).

#### Response Example
{
  "job_id": "abc123-def456-ghi789",
  "status": "completed",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:31:45Z",
  "result": {
    "markdown": "# Document Title\n\nExtracted content...",
    "page_count": 15,
    "bounding_boxes": {},
    "plan-info": {}
  }
}
```

--------------------------------

### GET /api/v1/charts/{charts_id}

Source: https://docs.runpulse.com/api-reference/endpoint/charts

Read one owned result by ID.

```APIDOC
## GET /api/v1/charts/{charts_id}

### Description
Read one owned result by ID.

### Method
GET

### Endpoint
/api/v1/charts/{charts_id}

### Parameters
#### Path Parameters
- **charts_id** (string) - Required - The unique identifier of the chart result.
```

--------------------------------

### Deploy Pipeline at Scale in Python

Source: https://docs.runpulse.com/api-reference/endpoint/pipeline-overview

Iterate through a list of documents to process them using saved configuration IDs and print the resulting schema output.

```python
from pulse import Pulse
import os

client = Pulse(api_key=os.environ["PULSE_API_KEY"])

documents = ["invoice_001.pdf", "invoice_002.pdf", "invoice_003.pdf"]

for doc_path in documents:
    # Extract
    result = client.extract(
        file=open(doc_path, "rb"),
        extraction_config_id="your-extraction-config-id"
    )
    
    # Apply schema using saved config
    schema_result = client.schema(
        extraction_id=result.extraction_id,
        schema_config_id="your-schema-config-id"
    )
    
    print(f"{doc_path}: {schema_result.schema_output['values']}")
```

--------------------------------

### Authenticate via CLI

Source: https://docs.runpulse.com/cli/overview

Command to initiate the browser-based login flow.

```bash
pulse login
```

--------------------------------

### GET /job/{job_id}

Source: https://docs.runpulse.com/api-reference/endpoint/poll

Retrieves the status and result of an asynchronous extraction job.

```APIDOC
## GET /job/{job_id}

### Description
Retrieves the current status and result of an asynchronous job. This endpoint is intended to be polled until the job status reaches 'completed', 'failed', or 'canceled'.

### Method
GET

### Endpoint
https://api.runpulse.com/job/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the job returned from the initial extraction request.

### Response
#### Success Response (200)
- **status** (string) - The current status of the job (e.g., 'pending', 'processing', 'completed', 'failed', 'canceled').
- **result** (object) - The extraction result data, present when status is 'completed'.
- **error** (string) - Error message, present when status is 'failed'.
```

--------------------------------

### GET /job/{job_id}

Source: https://docs.runpulse.com/api-reference/endpoint/charts

Polls the status and results of a chart extraction job.

```APIDOC
## GET /job/{job_id}

### Description
Polls the status of an asynchronous chart extraction job. Once the job reaches a terminal status, the result field contains the extracted chart data.

### Method
GET

### Endpoint
/job/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier for the extraction job.

### Response
#### Success Response (200)
- **charts_id** (string) - The ID of the completed chart result.
- **extraction_id** (string) - The ID associated with the extraction process.
- **page_range** (string) - The range of pages processed.
- **count** (integer) - Total number of charts found.
- **charts** (array) - List of extracted chart objects.
- **exports** (array) - List of available export files.
- **excel_url** (string) - URL to the Excel export file.
- **credits_used** (integer) - Number of credits consumed by the operation.

#### Response Example
{
  "charts_id": "90705060-b7b9-48c3-9593-7c7d62ce280e",
  "extraction_id": "0d904c3c-8eb8-4abd-a455-04c3a83c5b43",
  "page_range": "1-3,5",
  "count": 1,
  "charts": [
    {
      "id": "fig-1",
      "page_number": 2,
      "type": "line",
      "title": "Monthly price",
      "confidence": 0.94
    }
  ],
  "exports": [
    {
      "format": "excel",
      "filename": "charts.xlsx",
      "url": "https://api.runpulse.com/results/90705060-b7b9-48c3-9593-7c7d62ce280e/charts/charts.xlsx"
    }
  ],
  "credits_used": 1
}
```

--------------------------------

### Using schema_prompt for Contextual Guidance

Source: https://docs.runpulse.com/api-reference/structured-output-guidelines

Providing natural language instructions within the schema_prompt field to clarify extraction requirements.

```json
{
  "extraction_id": "abc123-...",
  "schema_config": {
    "input_schema": {
      "type": "object",
      "properties": {
        "contract_type": {"type": "string"},
        "effective_date": {"type": "string", "format": "date"},
        "parties": {"type": "array", "items": {"type": "string"}},
        "key_terms": {"type": "array", "items": {"type": "string"}}
      }
    },
    "schema_prompt": "Extract contract details. For key_terms, focus on payment terms, termination clauses, and liability limitations. Format dates as YYYY-MM-DD."
  }
}
```

--------------------------------

### Example bounding_boxes.Images Entry

Source: https://docs.runpulse.com/api-reference/endpoint/extract

A sample JSON object representing an entry in the bounding_boxes.Images array.

```json
{
  "id": "excel_image_1_1",
  "visual_type": "chart",
  "page_number": 1,
  "bounding_box": [],
  "image_url": "https://api.runpulse.com/results/13e3e75f-.../images/excel_image_1_1.png",
  "sheet_name": "Charts",
  "excel_range": "D2",
  "chart_type": "BarChart",
  "chart_title": "Revenue",
  "source_ranges": ["'Charts'!$A$2:$A$5", "'Charts'!$B$2:$B$5"],
  "description": "Bar chart showing revenue by quarter."
}
```

--------------------------------

### Configure Refinement Modes

Source: https://docs.runpulse.com/concepts/processing-parameters-core

Demonstrates the three ways to enable refinement: as a boolean, an array of modes, or an object containing both modes and a custom prompt.

```json
// Boolean — general refinement pass
{ "refine": true }

// Array — only the listed modes
{ "refine": ["tables", "text"] }

// Object — modes plus guidance in one place
{ "refine": { "modes": ["tables", "layout"], "prompt": "..." } }
```

--------------------------------

### Create Service Account Key

Source: https://docs.runpulse.com/storage/gcp-cloud-storage

Generate a JSON key file for the service account. Ensure this key is stored securely.

```bash
gcloud iam service-accounts keys create pulse-storage-key.json \
  --iam-account=pulse-storage-access@YOUR_PROJECT.iam.gserviceaccount.com
```

--------------------------------

### GET /results/{job_id}

Source: https://docs.runpulse.com/api-reference/endpoint/extract

Retrieves the full extraction result from a provided download URL.

```APIDOC
## GET /results/{job_id}

### Description
Fetches the complete JSON extraction result using the URL provided in the initial extraction response.

### Method
GET

### Endpoint
https://api.runpulse.com/results/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The identifier extracted from the initial response URL.
```

--------------------------------

### Initialize Pulse SDK with API Key

Source: https://docs.runpulse.com/api-reference/endpoint/results-image

Use the Pulse SDK constructor to automatically attach the x-api-key header to all requests, including results.getImage.

```python
Pulse(api_key=...)
```

```javascript
new PulseClient({ apiKey: ... })
```

--------------------------------

### GET /batch/{batch_id}

Source: https://docs.runpulse.com/api-reference/endpoint/batch-overview

Retrieves the current status and progress counts for a specific batch.

```APIDOC
## GET /batch/{batch_id}

### Description
Retrieves the status and progress metrics for a batch. This endpoint provides an O(1) status check regardless of batch size.

### Method
GET

### Endpoint
/batch/{batch_id}

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The unique identifier for the batch.

### Response
#### Success Response (200)
- **batch_id** (string) - The batch ID
- **status** (string) - "processing", "completed", "failed", or "canceled"
- **priority** (string) - As submitted (default "normal")
- **created_at** (string) - ISO timestamp
- **counts** (object) - total, pending, processing, succeeded, failed, canceled
- **jobs_url** (string) - Path to the paginated per-document drill-down
- **result_manifest_url** (string | null) - Downloadable NDJSON manifest of every child's outcome
```

--------------------------------

### GET /results/{jobId}

Source: https://docs.runpulse.com/api-reference/introduction

Download a completed result that is too large for inline job responses.

```APIDOC
## GET /results/{jobId}

### Description
Download a completed result that is too large for inline job responses.

### Method
GET

### Endpoint
/results/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The unique identifier of the job.
```

--------------------------------

### GET /job/{job_id}

Source: https://docs.runpulse.com/api-reference/endpoint/poll

Retrieves the current status and details of a specific job by its ID.

```APIDOC
## GET /job/{job_id}

### Description
Retrieves the status, creation timestamp, and result of a job identified by the provided job_id.

### Method
GET

### Endpoint
https://api.runpulse.com/job/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the job to retrieve.

### Response
#### Success Response (200)
- **job_id** (string) - The ID of the job.
- **status** (string) - The current status of the job (e.g., completed, failed).
- **created_at** (string) - The timestamp when the job was created.
- **result** (object) - The job output, containing the markdown result if completed.
- **error** (string) - Error message if the job status is failed.
```

--------------------------------

### Create a Service Account

Source: https://docs.runpulse.com/storage/gcp-cloud-storage

Create a dedicated service account for Pulse to manage storage access.

```bash
gcloud iam service-accounts create pulse-storage-access \
  --display-name="Pulse Storage Access" \
  --description="Service account for Pulse document extraction storage"
```

--------------------------------

### MPP payment recipe for agents

Source: https://docs.runpulse.com/advanced/mpp-payments

A step-by-step recipe for agents to extract documents and handle MPP payments using the Tempo wallet.

```text
Extract <document URL> with Pulse (https://api.runpulse.com/extract), paying over MPP:

1. POST {"file_url": "<document URL>"} with no credentials and read the 402
   WWW-Authenticate: Payment challenge.
2. Decode the challenge's base64url `request` field: it gives `amount` (USDC base
   units), `currency` (token contract), and a one-time `recipient` address.
3. Pay with:  tempo wallet transfer <amount ÷ 10⁶> <currency> <recipient>
   and keep the tx hash. Do not use `tempo request` — it cannot pay push-mode
   servers.
4. Retry the identical request with an Authorization: Payment <credential>
   header: base64url JSON echoing the challenge fields verbatim plus
   payload {"type": "hash", "hash": "<tx hash>"}.
5. Stop and ask me before paying if the quoted amount exceeds my budget.
```

--------------------------------

### GET /job/{job_id}

Source: https://docs.runpulse.com/api-reference/endpoint/charts

Retrieves the status and results of an asynchronous chart processing job.

```APIDOC
## GET /job/{job_id}

### Description
Poll this endpoint to check the status of an asynchronous job and retrieve the results once processing is complete.

### Method
GET

### Endpoint
/job/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier assigned to the asynchronous job.

### Response
#### Success Response (200)
- **job_id** (string) - Identifier assigned to the asynchronous job.
- **status** (string) - Current status of the job (pending, processing, completed, failed, canceled).
- **message** (string) - Human-readable description of the job status.
- **credits_used** (number) - Number of credits consumed by this request.
```

--------------------------------

### Defining Field Descriptions

Source: https://docs.runpulse.com/api-reference/structured-output-guidelines

Adding human-readable descriptions to properties to guide the extraction model.

```json
{
  "properties": {
    "invoice_number": {
      "type": "string",
      "description": "The unique invoice identifier, usually at the top of the document"
    },
    "bill_to": {
      "type": "string", 
      "description": "Customer billing address"
    },
    "remit_to": {
      "type": "string",
      "description": "Payment remittance address"
    }
  }
}
```

--------------------------------

### Integrate Pulse API with Python

Source: https://docs.runpulse.com/platform-reference/build-first-pipeline

A Python script demonstrating how to initialize the Pulse client, extract data from a PDF file, and retrieve schema-based output using a saved configuration ID.

```python
import os
from pulse import Pulse

client = Pulse(api_key=os.environ["PULSE_API_KEY"])

result = client.extract(
    file=open("invoice.pdf", "rb"),
)

schema_result = client.schema(
    extraction_id=result.extraction_id,
    schema_config_id="YOUR_SAVED_SCHEMA_CONFIG_ID",
)

print(schema_result.schema_output["values"])
```

--------------------------------

### Claude Desktop Node.js Verification

Source: https://docs.runpulse.com/mcp/connecting

Command to verify if Node.js is installed, which is required for the mcp-remote bridge.

```bash
npx --version
```
Tokens:
Raw