canonical: https://jentic.com/apis/import.io/import-io-extraction

# import.io Extraction API

The import.io Extraction API runs an adhoc extraction against a configured extractor and returns the result inline. The single endpoint GET `/extractor/{extractorId}` executes a one-off extraction, useful when the freshest data matters more than reading the most recent stored crawl run. Authentication is via an apikey query parameter. The API sits alongside the import.io data, run, schedule, and rss surfaces.

## For AI agents

Run an adhoc extraction against an import.io extractor and receive the result inline. Useful when the agent needs the freshest scraped data on demand.

## Scope

Does not schedule crawls, store results, or build extractors - use for one-off live extraction calls only.

## Capabilities

- Run an adhoc extraction for a configured extractor
- Receive structured extraction output in a single round trip
- Bypass crawl scheduling for time-sensitive lookups
- Power agent flows that need on-demand web data without waiting for a scheduled run

## Use cases

### On-Demand Web Data for Agents

When an AI agent needs the freshest version of a structured web dataset, calling the Extraction API runs the extractor immediately and returns the data inline. This avoids the latency of scheduling a run and then reading from the data API.

Example prompt: Run extractor ext-product-prices and return the resulting rows for analysis.

### Real-Time Pricing Lookup

E-commerce price intelligence agents can call this endpoint to fetch current competitor pricing on demand. The agent passes the extractor id; import.io executes the extraction and returns rows immediately, suitable for prompt-driven pricing decisions.

Example prompt: Run extractor ext-competitor-A-prices, parse the result, and return any SKU below 50 USD.

### Spot-Check Data Quality

Operations teams can spot-check the output of a configured extractor without running a full scheduled crawl. The single endpoint returns the current shape and content of extracted rows, useful for confirming a target page change has not broken the extractor before scheduling the next batch.

Example prompt: Run extractor ext-news-feed once and report the row count and the first row's column values.

### Jentic-Driven Live Scrape

Through Jentic, an agent searches for an extraction operation and runs the import.io extractor inline without learning the endpoint format. Jentic injects the apikey and returns the inline body for the agent to parse.

Example prompt: Search Jentic for 'run an extractor', load the schema, and execute with extractor id ext-jobs-board.

## Key resources

- **Adhoc Extraction** — Run an extractor on demand and receive the output inline

## Why Jentic

- **Setup:** Wiring the import.io Extraction API by hand means passing your apikey as a query parameter against the extraction.import.io host and building the live extraction call yourself. Through Jentic you install once, import the import.io Extraction API from the API Directory, store the apikey once, and your agent calls it.
- **Permission scoping:** The import.io Extraction API exposes a single live-extraction operation with its inputs in the request rather than a path resource id, so scope the agent to that one operation. Because you choose the allowed operations, the agent is limited to running the extractor you have named.
- **Credential handling:** Your import.io apikey is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run an extractor on a URL', and Jentic returns the Extraction API operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **import.io Data API** — Reads the latest stored crawl results rather than running extraction live
- **import.io Run API** — Starts and cancels longer crawl runs rather than inline extraction
- **ScraperAPI** — General-purpose proxy and scraping API for arbitrary URLs

## FAQ

### What authentication does the import.io Extraction API use?

The Extraction API uses an apikey query parameter on every request. Through Jentic, the apikey is stored in the encrypted vault and injected at runtime, so the agent never sees the raw key.

### Can I run an adhoc extraction with this API?

Yes. That is the only operation. GET `/extractor/{extractorId}` runs the configured extractor against its target and returns the resulting rows inline in the response body.

### What are the rate limits for the import.io Extraction API?

The spec does not declare hard rate limits. Adhoc extraction is more expensive than reading a stored crawl, so import.io enforces per-account concurrency and daily quotas that depend on plan tier.

### How do I run an adhoc extraction through Jentic?

Search Jentic for 'run an extractor' to find the operation backed by GET `/extractor/{extractorId}.` Load the schema, pass the extractor id, and execute. Jentic injects the apikey at runtime.

### When should I use Extraction versus the Data API?

Use Extraction when freshness matters and a single inline call is enough. Use the Data API when a scheduled crawl already populates results and reading the stored output is cheaper and faster than re-running extraction.

### Can I limit what my agent is allowed to do with the import.io Extraction API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent can use, and this API exposes just a single live-extraction operation (GET `/extractor/{extractorId}`). You scope the agent to that one operation and name the extractor it is allowed to run, so it cannot reach anything beyond the extraction you have permitted. Your import.io apikey stays stored and encrypted on your instance and is injected only at execution time, never entering the agent's prompt or logs.