Expanded Limits, Across all tiers - Our Gift to you! Learn more →

AlterLab
SearchResearchPricingComparePlaygroundBlogDocsChangelog
    AlterLabAlterLab
    PricingComparePlaygroundBlogDocsChangelog
    IntroductionQuickstartInstallationYour First Request
    REST APICrawl APIMap APISearch APIResearch APINewSERP APINewExtract APIAIJob PollingDomain StatsNewGeocode APINewNews APIBatch ResultsNewAPI KeysSessions APINewEnterprise APIEnterprise
    AccountAutoAI VisibilityAutoAlertsAutoAuthAutoBillingAutoCrawlAutoExtractAutoIntegrationsAutoKeysAutoMapAutoMonitorsAutoOrganizationsAutoResearch SchedulesAutoRunsAutoSchedulesAutoScrapeAutoSearchAutoSearch SchedulesAutoSessionsAutoUser WebhooksAutoV1 EndpointsAutoAffiliatesAutoAgentAutoAgent OnboardingAutoAgent VisibilityAutoAnalyticsAutoApprovalsAutoArtifactsAutoAttributionAutoB2BAutoBatchAutoBeta FeaturesAutoBlogAutoBuyerAutoChatAutoConnectionsAutoConnectorsAutoContact ListsAutoCreatorAutoCross SellAutoDashboardAutoDefaultsAutoDomainsAutoEmail PreferencesAutoFcAutoHandsAutoHealthAutoJobsAutoListingsAutoMaintenanceAutoNewsAutoOauthAutoOauth GrantsAutoPage InspectAutoPlatformAutoPresetsAutoPricingAutoPrivacyAutoPublicAutoPublic PagesAutoReferralAutoReferralsAutoReportsAutoResearchAutoSecretsAutoSerpAutoSSOAutoStorefrontsAutoSupportAutoTemplatesAutoToolsAutoTrackAutoUsageAutoUsage TagsAutoUserAutoWorkflowsAutoWorkspacesAutoWebhooksAuto
    OverviewPythonNode.jsCLI
    Guides OverviewJavaScript RenderingBrowser ActionsOutput FormatsPDF & OCRCachingWebhooksJSON Schema FilteringWebSocket Real-TimeBring Your Own ProxyProSticky SessionsProAuthenticated ScrapingNewHTTP Methods & BodiesNewStructured ExtractionAIWeb SearchAgent and RAG GroundingResearch JobsAgent RunsSite MappingWeb CrawlingBatch ScrapingSchedulerData MarketplaceSelling DataAgent OnboardingEmbeddingsKeyword IdeasAI VisibilityWorkflowsChange DetectionCloud Storage ExportSpend LimitsOrganizations & TeamsScrape TemplatesCustom ConnectorsSecretsContact ListsPlatform Sub-AccountsReferrals & AffiliatesAlerts & NotificationsExtraction ProfilesAIBYOK ExtractionAIOAuth2 Machine-to-MachineSupport & TicketsUnsupported Targets
    Tutorials OverviewStructured ExtractionAIE-commerce ScrapingNews MonitoringPrice MonitoringMulti-Page CrawlingMonitoring DashboardAI Agent / MCPMCPAI Research AgentAISite CrawlingData Pipeline to Cloud
    E-commerceLead GenerationChange MonitoringRAG & AI PipelinesAIResearch
    Reference OverviewPricingRate LimitsReliabilityReliability ContractError CodesChangelogVersioning
    Migrations OverviewFrom FirecrawlFrom ApifyFrom ScrapingBee / ScraperAPIFrom Crawl4AIFrom SpiderSearch to SERPFirecrawl v0 API ReferenceLegacy
    OverviewMCP ServerAIn8n NodeLangChainAICrewAIAILlamaIndexAISupabaseChrome ExtensionSoon
    PlaygroundPricingStatus

    Up to 5,000 free requests · No credit card

    API Reference
    Auto-generated

    Runs

    API reference for runs endpoints.

    Auto-generated

    This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

    POST /api/v1/runs

    POST
    /api/v1/runs

    Create a run from a plan and estimate it

    Parameters

    NameTypeRequiredDescription
    Idempotency-KeystringOptionalIdempotency-Key
    max_creditsinteger
    Required
    		Hard credit budget for the run (required)
    auto_approvebooleanOptionalAuto ApproveDefault: False
    webhook_urlstringOptionalwebhook_url
    dry_runbooleanOptionalValidate and estimate only; store nothingDefault: False
    dataset_idstringOptionaldataset_id
    stepsobject[]
    Required
    		Steps

    Request Example

    Bash
    curl -X POST https://api.alterlab.io/api/v1/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_credits": 0,
    "auto_approve": false,
    "dry_run": false
  }'

    Response Example

    JSON
    {
  "status": "ok"
}

    GET /api/v1/runs/{run_id}

    GET
    /api/v1/runs/{run_id}

    Get a run: state, estimate, spend and step summaries

    Parameters

    NameTypeRequiredDescription
    run_idstring
    Required
    		run_id

    Request Example

    Bash
    curl -X GET https://api.alterlab.io/api/v1/runs/<run_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "id": "example",
  "status": "example",
  "dry_run": true,
  "max_credits": 0,
  "auto_approve": true,
  "spent_credits": 0
}

    POST /api/v1/runs/{run_id}/approve

    POST
    /api/v1/runs/{run_id}/approve

    Approve a run: reserve its budget and start executing

    Parameters

    NameTypeRequiredDescription
    run_idstring
    Required
    		run_id
    max_creditsintegerOptionalmax_credits

    Request Example

    Bash
    curl -X POST https://api.alterlab.io/api/v1/runs/<run_id>/approve \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "id": "example",
  "status": "example",
  "dry_run": true,
  "max_credits": 0,
  "auto_approve": true,
  "spent_credits": 0
}

    POST /api/v1/runs/{run_id}/cancel

    POST
    /api/v1/runs/{run_id}/cancel

    Cancel a run: stop pending steps and refund the unused reserve

    Parameters

    NameTypeRequiredDescription
    run_idstring
    Required
    		run_id

    Request Example

    Bash
    curl -X POST https://api.alterlab.io/api/v1/runs/<run_id>/cancel \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "id": "example",
  "status": "example",
  "dry_run": true,
  "max_credits": 0,
  "auto_approve": true,
  "spent_credits": 0
}

    GET /api/v1/runs/{run_id}/events

    GET
    /api/v1/runs/{run_id}/events

    Stream run events (SSE, resumable)

    Parameters

    NameTypeRequiredDescription
    run_idstring
    Required
    		run_id
    last_event_idstringOptionallast_event_id
    Last-Event-IDstringOptionalLast-Event-ID

    Request Example

    Bash
    curl -X GET https://api.alterlab.io/api/v1/runs/<run_id>/events \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "status": "ok"
}

    GET /api/v1/runs/{run_id}/result

    GET
    /api/v1/runs/{run_id}/result

    The run's dataset version with per-field provenance

    Parameters

    NameTypeRequiredDescription
    run_idstring
    Required
    		run_id
    pageintegerOptionalpageDefault: 1
    page_sizeintegerOptionalpage_sizeDefault: 100
    format"json" | "ndjson"OptionalformatDefault: json

    Request Example

    Bash
    curl -X GET https://api.alterlab.io/api/v1/runs/<run_id>/result \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "run_id": "example",
  "dataset_id": "example",
  "version": "example",
  "page": 0,
  "page_size": 0,
  "total": 0
}
    Last updated: June 2026

    On this page