Scheduled Jobs (Cron)

What are scheduled jobs?

A scheduled job is a regular HTTP handler in your project that FloopFloop calls on a recurring schedule — every 5 minutes, every hour, daily at midnight, whatever you configure. Typical uses: polling an exchange for market data, refreshing a cache, sending a daily digest email, evaluating a strategy and placing a trade.

Each fire is a POST to a route under /api/cron/* inside your project, with a project-scoped bearer token that you verify before doing any work.

Adding a job from the dashboard

Open your project, go to Settings → Secrets, and scroll to the Scheduled Jobs section. Click Add cron job and fill in:

• Name — lowercase identifier, e.g. rebalance. This is also the default handler path.
• Schedule — pick a preset (every 5 minutes, hourly, daily at 00:00 UTC, etc.) or paste a standard 5-field cron expression. Cron runs in UTC.
• Handler path — defaults to /api/cron/<name>. The path must live under /api/cron/ — other paths are rejected.

After saving, the job shows up in the table with its next run time, last run status, and a toggle to pause it without deleting.

Writing the handler

Your handler is a normal Next.js POST route. Verify the bearer token against process.env.FLOOP_CRON_TOKEN before doing any work — any other request should get a 401:

// src/app/api/cron/rebalance/route.ts
import { NextRequest, NextResponse } from "next/server";

export const dynamic = "force-dynamic";

export async function POST(request: NextRequest) {
  const expected = `Bearer ${process.env.FLOOP_CRON_TOKEN ?? ""}`;
  if (request.headers.get("authorization") !== expected) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Do your work here — query data, call APIs, etc.
  return NextResponse.json({ ok: true });
}

The FLOOP_CRON_TOKENenvironment variable is managed by FloopFloop — it's baked into your project's runtime at build time and does not appear in the Secrets UI.

Auto-registration from templates

A template can declare its scheduled jobs up front by shipping a floop.crons.json file at its root:

{
  "jobs": [
    {
      "name": "evaluate-strategy",
      "cron": "*/5 * * * *",
      "path": "/api/cron/evaluate-strategy",
      "enabled": true
    }
  ]
}

After your first successful deploy, FloopFloop reads this manifest and auto-registers the jobs in your project's scheduled jobs list. You can edit the schedule or pause the job afterward without losing your changes on subsequent deploys.

Monitoring runs

The Scheduled Jobs table shows the status of the most recent fire: ok, error, or timeout. On errors, the last run's error message is stored so you can see what went wrong at a glance. Return a non-2xx HTTP status from your handler to mark the run as errored — the response body (up to 500 characters) is captured as the error message.

Limits & constraints

• 10 scheduled jobs per project.Paused jobs still count — delete ones you don't need.
• 1-minute minimum interval. Sub-minute cron expressions are rejected at save time.
• 30-second fetch timeout per fire. If your handler takes longer the dispatcher records a timeout and moves on.
• Fires only while your project is deployed and active — newly created projects and suspended projects are skipped silently and resume automatically on reactivation.
• Paths must match /api/cron/<name> — the restriction keeps cron firing away from your public-facing routes.