canonical: https://jentic.com/apis/import.io/import-io-run # import.io Run API The import.io Run API starts and cancels crawl runs for a configured extractor. Two endpoints, POST `/extractor/{extractorId}/start` and POST `/extractor/{extractorId}/cancel`, drive the run lifecycle. Authentication uses an apikey query parameter. The API pairs with the data, extraction, schedule, and rss surfaces in the import.io platform: Run starts work, RSS reports completion, and Data exposes the resulting rows. ## For AI agents Start and cancel crawl runs for an import.io extractor. Useful for triggering scraping work on demand from agents and pipelines. ## Scope Does not return crawl rows, schedule recurring runs, or build extractors - use for starting and cancelling individual runs only. ## Capabilities - Launch a new crawl run for a configured extractor - Cancel an in-progress crawl run - Drive run lifecycle from CI, schedulers, or agents - Pair with the RSS and Data APIs to deliver an end-to-end scrape pipeline ## Use cases ### On-Demand Crawl Launch Pipelines and agents that need fresh data from a saved extractor can call POST `/extractor/{extractorId}/start` to launch a run on demand. The Run API returns immediately; the run progresses asynchronously and results land in the Data API once complete. Example prompt: Start a crawl for extractor ext-prices and return the new run id. ### Long-Running Crawl Cancellation When a crawl is running too long or has been superseded by a newer request, agents can call POST `/extractor/{extractorId}/cancel` to stop the run. This frees up extractor concurrency without waiting for the run to time out naturally. Example prompt: Cancel the active crawl on extractor ext-prices and confirm the cancellation. ### Pipeline Refresh Trigger ETL pipelines that need fresh data before downstream steps can trigger a run via the Run API and then watch the RSS feed or poll the Data API for new output. This lets the pipeline drive freshness without depending on import.io's own schedules. Example prompt: Start extractor ext-news, wait for the run to appear in the RSS feed, then fetch the latest JSON from the Data API. ### Jentic-Triggered Scrape Through Jentic, an agent searches for a run-launching operation and starts the extractor without learning the endpoint. Jentic injects the apikey and the agent only supplies the extractor id; cancellation works the same way. Example prompt: Search Jentic for 'launch a crawl from an extractor', load the schema, and execute with extractor id ext-jobs. ## Key resources - **Run Start** — Launch a crawl run for an extractor - **Run Cancel** — Cancel an in-progress crawl run for an extractor ## Why Jentic - **Setup:** Wiring the import.io Run API by hand means passing your apikey as a query parameter and targeting the dedicated run.import.io host, separate from the rss and schedule hosts. Through Jentic you install once, import the import.io Run API from the API Directory, store the apikey once, and your agent calls it. - **Permission scoping:** The Run API covers starting and cancelling individual extractor runs, with the target passed in the request body, so limit the agent to the operations it needs, such as starting a run. You choose which operations are allowed, so cancelling runs is not included unless you add it. - **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 'launch a crawl' or 'cancel an extractor run', and Jentic returns the matching import.io Run 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 after the Run API completes a run - **import.io Schedule API** — Schedules recurring runs rather than triggering them ad hoc - **Apify** — Web scraping platform with native actor run lifecycle and webhooks ## FAQ ### What authentication does the import.io Run API use? The Run 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 raw key never enters agent prompts or logs. ### Can I cancel a crawl in progress? Yes. POST `/extractor/{extractorId}/cancel` cancels an active crawl on that extractor, freeing concurrency without waiting for natural timeout. The response confirms the cancellation. ### What are the rate limits for the import.io Run API? The published spec does not declare hard rate limits. import.io enforces per-account run concurrency that depends on plan tier, so agents should respect that ceiling and not start runs faster than the account can absorb. ### How do I trigger a crawl through Jentic? Search Jentic for 'launch a crawl from an extractor' to find the operation backed by POST `/extractor/{extractorId}/start.` Load the schema, pass the extractor id, and execute. Jentic injects the apikey at runtime. ### How do I read the results of a run started via this API? The Run API only starts and cancels work. Use the RSS API to detect when the run completes, then call the Data API at `/extractor/{extractorId}/json/latest` or `/csv/latest` to fetch the resulting rows. ### Can I limit what my agent is allowed to do with the import.io Run API? Yes. Because your Jentic One instance is self-hosted, you decide which import.io Run operations your agent may call, and it can only use the ones you allow. The Run API exposes just two operations, starting a crawl run and cancelling one, so you can permit the agent to start runs while withholding cancellation, or the reverse. Your own rules govern which operations and which stored apikey the agent may use, and any operation you do not grant stays off limits.