On-Demand Algorithm Execution

Run additional algorithms on existing job transcripts without re-transcribing audio. Webhook delivery is optional via the analytics_only flag.

The On-Demand Algorithm Execution API enables you to:

• Analytics-only processing: Run algorithms that store results but don't send webhooks
• Backfill historical data: Run new algorithms on existing transcripts
• Re-analysis: Re-run algorithms with updated configurations
• Ad-hoc analysis: Run one-off algorithms not configured during ingestion

Rerun supersession note: on-demand jobs are explicitly non-superseding (source_metadata.supersedes_parent: false). They never replace the original call's customer-visible result: the on-demand job is its own row in /calls/listing, and its runs are not folded into the original job's /runs response. Grading output from an on-demand job also never replaces the original call's grading in analytics dashboards; non-grading categories (e.g. call classification/intent) do attribute to the original call — that augmentation is the designed use of this endpoint. Use POST /jobs/{job_id}/retry with mode=rerun when the intent is to REPLACE the call's results.

When you call POST /api/v1/jobs/{job_id}/run-algorithms:

1. Creates a child job starting at analyzing state (skips transcription)
2. Copies the transcript from the original job
3. Runs only specified algorithms using requested_algorithm_ids
4. Respects analytics_only flag to skip webhook delivery
5. Stores results in algorithm_runs for the new job

The original job remains unchanged.

curl -X POST "https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm_ids": ["sentiment_v1", "competitor_mentions_v1"],
    "analytics_only": true
  }'

Response (202 Accepted):

{
  "job_id": 9500,
  "parent_job_id": 8835,
  "algorithm_ids": ["sentiment_v1", "competitor_mentions_v1"],
  "status": "analyzing",
  "message": "On-demand analysis job created"
}

Set analytics_only: false to send results via configured webhooks:

curl -X POST "https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm_ids": ["appointment_scheduling"],
    "analytics_only": false
  }'

Note: The child job uses its own webhook settings, NOT the parent's. Set analytics_only: false to enable webhooks even if the parent was analytics-only.

After creating the on-demand job, poll for status and results:

# Check job status
curl "https://analytics-api.gensail.com/api/v1/jobs/9500" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get algorithm run results
curl "https://analytics-api.gensail.com/api/v1/jobs/9500/runs" \
  -H "Authorization: Bearer YOUR_TOKEN"

By default, if the requested algorithms already ran on the original job, the API returns the existing runs:

{
  "message": "Algorithms already ran on this job",
  "existing_runs": [
    {"algorithm_run_id": 2001, "algorithm_id": "sentiment_v1", "status": "completed"}
  ],
  "hint": "Use force_rerun=true to run again"
}

Use force_rerun: true to bypass this check and create a new job:

curl -X POST "https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm_ids": ["appointment_scheduling"],
    "force_rerun": true
  }'

Requested algorithms must be available to the workspace. Available algorithms include:

1. Global algorithms (partner_id = NULL, organization_id = NULL)
2. Partner-scoped algorithms (linked via partner → organization)
3. Workspace-assigned algorithms (explicitly enabled for the workspace)

If an algorithm is not available, the API returns a 400 error:

{
  "detail": "Algorithms not available: ['unknown_algo']"
}

The original job must meet these requirements:

Run a new algorithm on all completed jobs from the past month:

import requests

# List completed jobs from the past month
jobs_response = requests.get(
    "https://analytics-api.gensail.com/api/v1/jobs",
    params={"status": "completed", "since": "30d"},
    headers={"Authorization": f"Bearer {TOKEN}"}
)

# Run the new algorithm on each job
for job in jobs_response.json()["jobs"]:
    requests.post(
        f"https://analytics-api.gensail.com/api/v1/jobs/{job['job_id']}/run-algorithms",
        json={"algorithm_ids": ["new_sentiment_v2"]},
        headers={"Authorization": f"Bearer {TOKEN}"}
    )

Store algorithm outputs without triggering partner webhooks:

curl -X POST "https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm_ids": ["internal_metrics_v1", "qa_scoring_v1"],
    "analytics_only": true
  }'

Results are stored in algorithm_runs and available via GET /jobs/{id}/runs.

Re-run an algorithm with updated prompts/configuration:

# Run the updated algorithm version
curl -X POST "https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm_ids": ["rise_dds_v5"],
    "analytics_only": true
  }'

Compare results from the child job (v5) with the original job (v4).

The endpoint uses scope-based rate limits matching other authenticated endpoints:

• Workspace keys: 50 requests/minute
• Organization keys: 120 requests/minute
• Partner keys: 500 requests/minute

For large backfills, implement client-side throttling:

• Batch requests appropriately for your key scope
• Use exponential backoff on 429 responses

• Job Status API - Poll job status
• Algorithm Runs API - Fetch algorithm results
• Webhook Payloads - Webhook payload format

For questions about on-demand algorithm execution, contact support@gensail.com.