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.

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.

How jobs are registered

Scheduled jobs are declared by the template, not added by hand. A template ships 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 registers the jobs for your project. Registration is idempotent — redeploying the same template will not duplicate jobs or reset any run history.

If your app needs a different schedule, ask FloopFloop in chat to update the template's floop.crons.json; the new cadence takes effect after the next deploy.

Run status

Each fire is recorded with a status of ok, error, or timeout. 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 for debugging.

Limits & constraints

• 10 scheduled jobs per project. Templates declaring more than 10 entries in floop.crons.json have the overflow rejected at registration.
• 1-minute minimum interval. Sub-minute cron expressions are rejected at registration 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.