---
title: "Run one survey now, on top of the schedule"
method: POST
path: "/trackers/{id}/survey"
tags: ["Trackers"]
---

# Run one survey now, on top of the schedule

`POST /trackers/{id}/survey`

## Request

- Base URL: `https://api.epovest.com/v1`
- URL: `https://api.epovest.com/v1/trackers/{id}/survey`
- Auth: HTTP bearer

Runs one survey NOW: the anchor, the frequency and the date of the next scheduled survey are
untouched. Answers `201` with the survey, which carries `on_demand: true` and `requested_at`;
its point joins the series under the same period, told apart by `on_demand`. On a tracker
whose frequency is `on_demand`, this is where every survey after the first one comes from.
Debits the balance like any survey. While one is still running, answers `200` with THAT
survey.
A refusal never pauses the tracker: the schedule asked for nothing and keeps running.
Owner only.

## Response `200`

A survey of this tracker was already running: it is the one that comes back.

- object
  - `survey` Survey, required
    - `id` string, uuid, required
    - `period_start` string, date, required
    - `status` 'pending' | 'running' | 'completed' | 'failed', required
    - `panel_version` integer, required: The tracker version that ran it, the series spanning versions.
    - `on_demand` boolean, required: True when the survey was asked for on the tracker rather than run by the cadence.
    - `requested_at` string, date-time, nullable, required
    - `started_at` string, date-time, nullable, required
    - `completed_at` string, date-time, nullable, required
    - `billed_analysts` AnalystType[], required: The AI analysts reserved on that survey, snapshotted at creation, what the credit hold covered. Empty when none.

## Other responses

- `201`: The survey that was just started.
- `401`: `unauthenticated`: missing, unknown or revoked key.
- `402`: `insufficient_credits`: the balance does not cover one survey. The answer carries `cost_per_survey_minor` and `available_minor`, so you can name the shortfall to the person, and `top_up_url`, the page where they add credit: hand it to them.
- `403`: `insufficient_scope`: the credential may not do this, either because the key lacks the scope, or, on a one-click connection, because the person lacks the role the action needs (manager, or owner to start, pause and top up). On that path, read it as "this person may not do this" and tell them which role the action needs.
- `404`: `not_found`: unknown for this account.
- `409`: The refusal names the move that unblocks: `tracker_not_active` (start it first), `tracker_archived` (bring it back first), `already_starting` (another call is starting one right now, nothing spent).
- `429`: `rate_limited`: 120 requests per minute per credential, sliding window. Retry after `Retry-After` seconds.
- `503`: `service_unavailable`: a backend is unreachable; retry later.

---

[API](https://skmtc.dev/epovest/apis/epovest-api.md) · [All operations](https://skmtc.dev/epovest/apis/epovest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/epovest/apis/epovest-api/revisions/7a78ee27ecbb?raw)