Start and monitor scoring

Scoring is an asynchronous, explicitly initiated operation. It never runs when a participant completes a survey.

curl --request POST \
  "https://api.getramon.com/integrations/v1/surveys/YOUR_SURVEY_ID/scoring-runs" \
  --header "Authorization: Bearer YOUR_INTEGRATION_KEY" \
  --header "Content-Type: application/json" \
  --data '{"force":false}'

The endpoint returns 202 Accepted with a run in running, completed, or failed state. If a run is already active for the survey, Ramon returns that run instead of starting a concurrent one.

Poll the run until it is terminal:

curl "https://api.getramon.com/integrations/v1/surveys/YOUR_SURVEY_ID/scoring-runs/YOUR_RUN_ID" \
  --header "Authorization: Bearer YOUR_INTEGRATION_KEY"

The result includes total, scored, skipped, failed, optional failures, and timestamps. Use force: false for normal runs; it leaves already scored sessions skipped. Use force: true only when a deliberate rescore is needed. After completion, call session lookup to read humanScorePercent, scoreBand, scoredAt, and modelVersion.

Failure behavior

Poll at a bounded interval, respect rate limiting, and surface a failed run's error and failures to an administrator. Do not block participant flow while a run is pending or fails.

Failure behavior​

Failure behavior