{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-gensail-analytics/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"On-Demand Algorithm Execution","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"on-demand-algorithm-execution","__idx":0},"children":["On-Demand Algorithm Execution"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run additional algorithms on existing job transcripts without re-transcribing audio. Webhook delivery is optional via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["analytics_only"]}," flag."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The On-Demand Algorithm Execution API enables you to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Analytics-only processing"]},": Run algorithms that store results but don't send webhooks"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Backfill historical data"]},": Run new algorithms on existing transcripts"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Re-analysis"]},": Re-run algorithms with updated configurations"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Ad-hoc analysis"]},": Run one-off algorithms not configured during ingestion"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rerun supersession note:"]}," on-demand jobs are explicitly"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["non-superseding"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source_metadata.supersedes_parent: false"]},"). They never"," ","replace the original call's customer-visible result: the on-demand job is"," ","its own row in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/calls/listing"]},", and its runs are not folded into the"," ","original job's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /jobs/{job_id}/retry"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mode=rerun"]}," when the intent is to"," ","REPLACE the call's results."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":2},"children":["How It Works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/jobs/{job_id}/run-algorithms"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Creates a child job"]}," starting at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["analyzing"]}," state (skips transcription)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Copies the transcript"]}," from the original job"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Runs only specified algorithms"]}," using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requested_algorithm_ids"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Respects ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["analytics_only"]}]}," flag to skip webhook delivery"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stores results"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["algorithm_runs"]}," for the new job"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The original job remains unchanged."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"basic-usage","__idx":3},"children":["Basic Usage"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"run-analytics-only-algorithms","__idx":4},"children":["Run Analytics-Only Algorithms"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"algorithm_ids\": [\"sentiment_v1\", \"competitor_mentions_v1\"],\n    \"analytics_only\": true\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (202 Accepted):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"job_id\": 9500,\n  \"parent_job_id\": 8835,\n  \"algorithm_ids\": [\"sentiment_v1\", \"competitor_mentions_v1\"],\n  \"status\": \"analyzing\",\n  \"message\": \"On-demand analysis job created\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"run-with-webhook-delivery","__idx":5},"children":["Run with Webhook Delivery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["analytics_only: false"]}," to send results via configured webhooks:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"algorithm_ids\": [\"appointment_scheduling\"],\n    \"analytics_only\": false\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," The child job uses its own webhook settings, NOT the parent's. Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["analytics_only: false"]}," to enable webhooks even if the parent was analytics-only."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"poll-for-results","__idx":6},"children":["Poll for Results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After creating the on-demand job, poll for status and results:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Check job status\ncurl \"https://analytics-api.gensail.com/api/v1/jobs/9500\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Get algorithm run results\ncurl \"https://analytics-api.gensail.com/api/v1/jobs/9500/runs\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-parameters","__idx":7},"children":["Request Parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["algorithm_ids"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string[]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Algorithms to run (1-10, duplicates auto-deduped)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["analytics_only"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Skip webhook delivery"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["force_rerun"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Run even if algorithms already ran"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency","__idx":8},"children":["Idempotency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, if the requested algorithms already ran on the original job, the API returns the existing runs:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"message\": \"Algorithms already ran on this job\",\n  \"existing_runs\": [\n    {\"algorithm_run_id\": 2001, \"algorithm_id\": \"sentiment_v1\", \"status\": \"completed\"}\n  ],\n  \"hint\": \"Use force_rerun=true to run again\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["force_rerun: true"]}," to bypass this check and create a new job:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"algorithm_ids\": [\"appointment_scheduling\"],\n    \"force_rerun\": true\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"algorithm-availability","__idx":9},"children":["Algorithm Availability"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requested algorithms must be available to the workspace. Available algorithms include:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Global algorithms"]}," (partner_id = NULL, organization_id = NULL)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Partner-scoped algorithms"]}," (linked via partner → organization)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workspace-assigned algorithms"]}," (explicitly enabled for the workspace)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If an algorithm is not available, the API returns a 400 error:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"detail\": \"Algorithms not available: ['unknown_algo']\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validation-requirements","__idx":10},"children":["Validation Requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The original job must meet these requirements:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Requirement"},"children":["Requirement"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error"},"children":["Error"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Job must exist"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404 Not Found"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Auth must have access"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403 Forbidden"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Job must be completed/partial/failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400 \"Job is still {status}. Wait for completion.\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transcript must exist and be non-empty"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400 \"Job has no usable transcript\""]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-cases","__idx":11},"children":["Use Cases"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"backfill-historical-data","__idx":12},"children":["Backfill Historical Data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run a new algorithm on all completed jobs from the past month:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\n# List completed jobs from the past month\njobs_response = requests.get(\n    \"https://analytics-api.gensail.com/api/v1/jobs\",\n    params={\"status\": \"completed\", \"since\": \"30d\"},\n    headers={\"Authorization\": f\"Bearer {TOKEN}\"}\n)\n\n# Run the new algorithm on each job\nfor job in jobs_response.json()[\"jobs\"]:\n    requests.post(\n        f\"https://analytics-api.gensail.com/api/v1/jobs/{job['job_id']}/run-algorithms\",\n        json={\"algorithm_ids\": [\"new_sentiment_v2\"]},\n        headers={\"Authorization\": f\"Bearer {TOKEN}\"}\n    )\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"analytics-only-data-lake","__idx":13},"children":["Analytics-Only Data Lake"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store algorithm outputs without triggering partner webhooks:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"algorithm_ids\": [\"internal_metrics_v1\", \"qa_scoring_v1\"],\n    \"analytics_only\": true\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Results are stored in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["algorithm_runs"]}," and available via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /jobs/{id}/runs"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"compare-algorithm-versions","__idx":14},"children":["Compare Algorithm Versions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Re-run an algorithm with updated prompts/configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Run the updated algorithm version\ncurl -X POST \"https://analytics-api.gensail.com/api/v1/jobs/8835/run-algorithms\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"algorithm_ids\": [\"rise_dds_v5\"],\n    \"analytics_only\": true\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Compare results from the child job (v5) with the original job (v4)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limiting","__idx":15},"children":["Rate Limiting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The endpoint uses scope-based rate limits matching other authenticated endpoints:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workspace keys"]},": 50 requests/minute"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Organization keys"]},": 120 requests/minute"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Partner keys"]},": 500 requests/minute"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For large backfills, implement client-side throttling:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Batch requests appropriately for your key scope"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use exponential backoff on 429 responses"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-documentation","__idx":16},"children":["Related Documentation"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/gensail-analytics/openapi/openapi"},"children":["Job Status API"]}," - Poll job status"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/gensail-analytics/openapi/openapi"},"children":["Algorithm Runs API"]}," - Fetch algorithm results"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/gensail-analytics/guides/webhook-payloads"},"children":["Webhook Payloads"]}," - Webhook payload format"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"support","__idx":17},"children":["Support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For questions about on-demand algorithm execution, contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@gensail.com"},"children":["support@gensail.com"]},"."]}]},"headings":[{"value":"On-Demand Algorithm Execution","id":"on-demand-algorithm-execution","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"How It Works","id":"how-it-works","depth":2},{"value":"Basic Usage","id":"basic-usage","depth":2},{"value":"Run Analytics-Only Algorithms","id":"run-analytics-only-algorithms","depth":3},{"value":"Run with Webhook Delivery","id":"run-with-webhook-delivery","depth":3},{"value":"Poll for Results","id":"poll-for-results","depth":3},{"value":"Request Parameters","id":"request-parameters","depth":2},{"value":"Idempotency","id":"idempotency","depth":2},{"value":"Algorithm Availability","id":"algorithm-availability","depth":2},{"value":"Validation Requirements","id":"validation-requirements","depth":2},{"value":"Use Cases","id":"use-cases","depth":2},{"value":"Backfill Historical Data","id":"backfill-historical-data","depth":3},{"value":"Analytics-Only Data Lake","id":"analytics-only-data-lake","depth":3},{"value":"Compare Algorithm Versions","id":"compare-algorithm-versions","depth":3},{"value":"Rate Limiting","id":"rate-limiting","depth":2},{"value":"Related Documentation","id":"related-documentation","depth":2},{"value":"Support","id":"support","depth":2}],"frontmatter":{"seo":{"title":"On-Demand Algorithm Execution"}},"lastModified":"2026-07-11T04:47:01.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/gensail-analytics/guides/on-demand-algorithms","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}