ProTox-3 API & automation

Drive ProTox-3 from the jobs API or the ivybloom CLI to fold toxicity screening into a pipeline — submit compounds, select which of the 61 endpoints to run, poll to completion, and pull predictions with confidence scores back into your workflow. The compounds and the endpoint set you request determine both what the job returns and how much of your daily quota it consumes.

API workflow

1. Submit a job: create a job with tool protox3, your compounds, and the toxicity models to run.
2. Poll status: check the job status until it reaches succeeded or failed.
3. Download results: retrieve the CSV/JSON artifacts once the job completes.

Request template

POST /api/v1/jobs
Content-Type: application/json

{
  "tool_name": "protox3",
  "tool_input_parameters": {
    "compounds": ["CC(=O)OC1=CC=CC=C1C(=O)O"],
    "models": ["acute_tox", "dili"]
  }
}

• Provide compounds as canonical SMILES, or as compound names for PubChem lookup (as in the webapp).
• Select specific models to keep runtime and daily-quota use down, or request the comprehensive panel to run all 61 endpoints.
• Keep each job within the 50-compound cap; split larger sets across jobs. See limits & performance.

Polling status

• Poll the job status endpoint until succeeded or failed; use exponential backoff rather than a tight loop.
• Respect rate-limit and backoff headers — ProTox-3 also enforces a shared 250-queries-per-day quota, so pace automated submissions accordingly.
• Capture the model version from job metadata for reproducibility.

Downloading results

• Fetch the CSV/JSON artifacts after completion via the artifact endpoint.
• Results include per-compound predictions with confidence scores, structural alerts, and similar known toxic compounds.
• Store the job URL alongside artifacts in downstream systems (ELN, tickets) for traceability.

Error handling

• Inspect the job log to separate validation errors (bad SMILES, failed name lookup) from service errors.
• Invalid SMILES are reported per compound; valid compounds still return, so you keep partial coverage.
• Retry only idempotent submissions on transient failures; do not resubmit malformed payloads.

Batch processing

• Submit up to 50 compounds in a single job; attach a project ID to group retries and align quota attribution.
• Track progress on the job page for large batches.
• Partial results are available when individual compounds fail validation.

Read next