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

    Research Schedules

    API reference for research schedules endpoints.

    Auto-generated

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

    POST /api/v1/research/schedules

    POST
    /api/v1/research/schedules

    Create a research schedule

    Parameters

    NameTypeRequiredDescription
    X-Organization-IdstringOptionalX-Organization-Id
    namestring
    Required
    		Name
    cronstring
    Required
    		Cron expression (5 fields), e.g. '0 9 * * *'
    timezonestringOptionalTimezoneDefault: UTC
    research_configobject
    Required
    		Frozen research request run on each schedule tick. The webhook lives on the schedule (''webhook_url'') and a fresh signing secret is minted per run; plan approval would stall an unattended run, so ''plan_first'' is rejected.
    webhook_urlstringOptionalwebhook_url

    Request Example

    Bash
    curl -X POST https://api.alterlab.io/api/v1/research/schedules \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example_name",
    "cron": "example_cron",
    "timezone": "example_timezone",
    "research_config": "..."
  }'

    Response Example

    JSON
    {
  "status": "ok"
}

    GET /api/v1/research/schedules

    GET
    /api/v1/research/schedules

    List research schedules

    Parameters

    NameTypeRequiredDescription
    limitintegerOptionallimitDefault: 20
    offsetintegerOptionaloffsetDefault: 0
    active_onlybooleanOptionalactive_onlyDefault: False

    Request Example

    Bash
    curl -X GET https://api.alterlab.io/api/v1/research/schedules \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "schedules": [],
  "total": 0
}

    GET /api/v1/research/schedules/{schedule_id}

    GET
    /api/v1/research/schedules/{schedule_id}

    Get research schedule details

    Parameters

    NameTypeRequiredDescription
    schedule_idstring
    Required
    		schedule_id

    Request Example

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

    Response Example

    JSON
    {
  "id": "example",
  "name": "example",
  "cron": "example",
  "timezone": "example",
  "research_config": {},
  "webhook_url": "example"
}

    PATCH /api/v1/research/schedules/{schedule_id}

    PATCH
    /api/v1/research/schedules/{schedule_id}

    Update a research schedule

    Parameters

    NameTypeRequiredDescription
    schedule_idstring
    Required
    		schedule_id
    namestringOptionalname
    cronstringOptionalcron
    timezonestringOptionaltimezone
    research_configobjectOptionalFrozen research request run on each schedule tick. The webhook lives on the schedule (''webhook_url'') and a fresh signing secret is minted per run; plan approval would stall an unattended run, so ''plan_first'' is rejected.
    webhook_urlstringOptionalwebhook_url
    enabledbooleanOptionalenabled

    Request Example

    Bash
    curl -X PATCH https://api.alterlab.io/api/v1/research/schedules/<schedule_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "id": "example",
  "name": "example",
  "cron": "example",
  "timezone": "example",
  "research_config": {},
  "webhook_url": "example"
}

    DELETE /api/v1/research/schedules/{schedule_id}

    DELETE
    /api/v1/research/schedules/{schedule_id}

    Delete a research schedule

    Parameters

    NameTypeRequiredDescription
    schedule_idstring
    Required
    		schedule_id

    Request Example

    Bash
    curl -X DELETE https://api.alterlab.io/api/v1/research/schedules/<schedule_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "status": "ok"
}

    POST /api/v1/research/schedules/{schedule_id}/pause

    POST
    /api/v1/research/schedules/{schedule_id}/pause

    Pause a research schedule

    Parameters

    NameTypeRequiredDescription
    schedule_idstring
    Required
    		schedule_id

    Request Example

    Bash
    curl -X POST https://api.alterlab.io/api/v1/research/schedules/<schedule_id>/pause \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "id": "example",
  "name": "example",
  "cron": "example",
  "timezone": "example",
  "research_config": {},
  "webhook_url": "example"
}

    POST /api/v1/research/schedules/{schedule_id}/resume

    POST
    /api/v1/research/schedules/{schedule_id}/resume

    Resume a paused research schedule

    Parameters

    NameTypeRequiredDescription
    schedule_idstring
    Required
    		schedule_id

    Request Example

    Bash
    curl -X POST https://api.alterlab.io/api/v1/research/schedules/<schedule_id>/resume \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "id": "example",
  "name": "example",
  "cron": "example",
  "timezone": "example",
  "research_config": {},
  "webhook_url": "example"
}

    POST /api/v1/research/schedules/{schedule_id}/run

    POST
    /api/v1/research/schedules/{schedule_id}/run

    Manually trigger a research schedule run

    Parameters

    NameTypeRequiredDescription
    schedule_idstring
    Required
    		schedule_id

    Request Example

    Bash
    curl -X POST https://api.alterlab.io/api/v1/research/schedules/<schedule_id>/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

    Response Example

    JSON
    {
  "id": "example",
  "schedule_id": "example",
  "status": "example",
  "job_id": "example",
  "error": "example",
  "started_at": "example"
}

    GET /api/v1/research/schedules/{schedule_id}/runs

    GET
    /api/v1/research/schedules/{schedule_id}/runs

    List research schedule run history

    Parameters

    NameTypeRequiredDescription
    schedule_idstring
    Required
    		schedule_id
    limitintegerOptionallimitDefault: 20
    offsetintegerOptionaloffsetDefault: 0

    Request Example

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

    Response Example

    JSON
    {
  "runs": [],
  "total": 0
}
    Last updated: June 2026

    On this page