Quickstart

This guide takes you from an API key to your first results: you parse a sample bank statement, extract two fields from it, and read both results.

Get an API key

Create a key in the Pulse dashboard under API Keys, as Authentication describes. Then set it as an environment variable, so the examples below can read it:

export PULSE_API_KEY="your-api-key"

Install an SDK

Install the Python or TypeScript SDK. To call the API with cURL instead, skip this step.

pip install pulse-ai

npm install @pulse-software/sdk

The SDKs send your key and the Pulse-Version: 2 header on every request. With cURL, you send both headers yourself.

Parse a document

This request parses the sample statement from its URL and waits for the parse to finish. config.model is the only option you must send.

import os
from pulse import Pulse

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

job = client.parse.run(
    file_url="https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
    config={"model": "ultra-2"},
)
parse_id = job.parse_id

import { PulseClient } from "@pulse-software/sdk";

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

const { parseId } = await client.parse.run({
  fileUrl: "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
  config: { model: "ultra-2" },
});

curl -X POST https://api.runpulse.com/parse \
  -H "x-api-key: $PULSE_API_KEY" \
  -H "Pulse-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
    "config": {"model": "ultra-2"}
  }'

The response names the parse. It doesn’t hold the content: you read that from the parse’s result route in the last step.

{
  "parse_id": "parse-3f6c2a9e-8d4b-4c1a-9e0f-5b7d2c8a1e64",
  "created_at": "2026-10-29T17:02:11.482913Z",
  "completed_at": "2026-10-29T17:02:19.105377Z"
}

To send a file from disk instead of a URL, send it as file: see Files and limits. For long documents, send async: true to get the parse_id right away, then poll the job: see Jobs and results.

Extract fields

This request sends the parse_id to Extract with a JSON Schema of the two fields you want. It waits for the extraction to finish and returns its extract_id.

job = client.extract.run(
    parse_id=parse_id,
    config={
        "input_schema": {
            "type": "object",
            "properties": {
                "account_holder": {"type": "string"},
                "closing_balance": {"type": "number"},
            },
        }
    },
)
extract_id = job.extract_id

const { extractId } = await client.extract.run({
  parseId,
  config: {
    inputSchema: {
      type: "object",
      properties: {
        account_holder: { type: "string" },
        closing_balance: { type: "number" },
      },
    },
  },
});

PARSE_ID=parse-3f6c2a9e-8d4b-4c1a-9e0f-5b7d2c8a1e64  # the parse_id from the previous step

curl -X POST https://api.runpulse.com/extract \
  -H "x-api-key: $PULSE_API_KEY" \
  -H "Pulse-Version: 2" \
  -H "Content-Type: application/json" \
  --data @- <<EOF
{
  "parse_id": "$PARSE_ID",
  "config": {
    "input_schema": {
      "type": "object",
      "properties": {
        "account_holder": {"type": "string"},
        "closing_balance": {"type": "number"}
      }
    }
  }
}
EOF

Read the results

This code reads the extraction’s values, then the parse’s Markdown.

extraction = client.extract.get_result(extract_id)
print(extraction.extraction.enriched)

parse = client.parse.get_result(parse_id)
print(parse.markdown[:500])

const extraction = await client.extract.getResult({ extractId });
console.log(extraction.extraction.enriched);

const parse = await client.parse.getResult({ parseId });
console.log(parse.markdown.slice(0, 500));

EXTRACT_ID=extract-…  # the extract_id from the previous step

curl https://api.runpulse.com/extract/$EXTRACT_ID/result \
  -H "x-api-key: $PULSE_API_KEY" \
  -H "Pulse-Version: 2"

curl https://api.runpulse.com/parse/$PARSE_ID/result \
  -H "x-api-key: $PULSE_API_KEY" \
  -H "Pulse-Version: 2"

In the extraction, each field comes back as {value, citation, confidence}. The citation names the parse elements the value was read from.In the parse, markdown is the document in reading order. elements holds the same content as text blocks, tables and figures, each with an id, a page and its position on the page. See Elements and bounding boxes.

Some organizations delete each result the first time it’s read. There, finish every step on a parse before you read the parse’s result, as this guide does, or run them together in a pipeline.

The parse costs 1 credit per page, and the extraction 1 credit per page it reads. See Pricing for every step.

Next steps

Parse

Add figures, refine passes, spreadsheet options, footnotes and chunks.

Extract

Write schemas, read citations, and choose the effort level.

Jobs and results

Run jobs async, poll their status, and learn how long results are kept.

Pipelines

Parse a document and run several steps on it in one call.

Get started

Endpoints

Run at scale

Essentials

Account

Next steps

Parse

Extract

Jobs and results

Pipelines

​Next steps

Parse

Extract

Jobs and results

Pipelines

Next steps