API reference

Jobs

Submit, track, and download long-running compute jobs.

On this page

Estimate job reservation cost

POST/api/v1/jobs/estimate

API key or token

Price one job at your plan's rates without submitting it.

Uses the same reservation math as submit, so cost is what submitting would reserve. An incomplete payload still returns a scaled estimate, with assumptions.validated false.

Request body

application/json · JobEstimateRequest

Request fields
Field	Type	Description
`job_type`required	`string`
`payload`required	`object`
`resource`	`string`	Default: `"default"`

Example request

curl -X POST "https://api.cognichem.com/api/v1/jobs/estimate" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "job_type": "admet-predict",
  "payload": {
    "input_data": [
      "CCO",
      "c1ccccc1"
    ],
    "input_format": "smiles",
    "thresholds": [
      {
        "endpoint": "admet_herg",
        "op": "lt",
        "value": 0.3
      }
    ]
  },
  "resource": "default"
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.estimate(
    job_type="admet-predict",
    payload={
        "input_data": ["CCO", "c1ccccc1"],
        "input_format": "smiles",
        "thresholds": [{"endpoint": "admet_herg", "op": "lt", "value": 0.3}],
    },
    resource="default",
)
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · JobEstimateResponse

Response fields
Field	Type	Description
`assumptions`	`object`	Default: `{}`
`cost`required	`number`
`expected_runtime_sec`required	`number`
`job_type`required	`string`
`rate_per_sec`required	`number`
`resource`required	`string`
`tier`required	`integer`

Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Submit a job

POST/api/v1/jobs/submit

API key or tokenCharges your wallet

Submit a new job for the current user.

Parameters

Headers
Name	Type	Description
`Idempotency-Key`	`string`	A unique key (a UUID) for this request. Retrying with the same key and body returns the first result instead of repeating the work; the same key with a different body is a 409.

Request body

application/json · JobSubmitRequest

Request fields
Field	Type	Description
`job_name`required	`string`	Name of the job.
`job_type`required	`string`	Type of the job.
`payload`required	`object`	Job-specific parameters.
`resource`	`string`	The computational resource to be used for the job (e.g., "cpu", "a10", "h100"). Defaults to "default", which is job-specific. Default: `"default"`

Example request

curl -X POST "https://api.cognichem.com/api/v1/jobs/submit" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "job_name": "catalog-admet-predict",
  "job_type": "admet-predict",
  "payload": {
    "input_data": [
      "CCO",
      "c1ccccc1"
    ],
    "input_format": "smiles",
    "thresholds": [
      {
        "endpoint": "admet_herg",
        "op": "lt",
        "value": 0.3
      }
    ]
  },
  "resource": "default"
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.submit(
    job_name="catalog-admet-predict",
    job_type="admet-predict",
    payload={
        "input_data": ["CCO", "c1ccccc1"],
        "input_format": "smiles",
        "thresholds": [{"endpoint": "admet_herg", "op": "lt", "value": 0.3}],
    },
    resource="default",
)
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY. The SDK sends an Idempotency-Key; pass idempotency_key= to reuse one when you retry.

Responses

Successful Response · application/json · JobSubmitResponse

Response fields
Field	Type	Description
`process_id`required	`string`	Unique identifier of the submitted job.

Example 200 response

{
  "process_id": "fc-01HZXY9ABCDEF1234567890"
}

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Submit several jobs

POST/api/v1/jobs/submit-multiple

API key or tokenCharges your wallet

Submit multiple jobs in a single request.

Parameters

Headers
Name	Type	Description
`Idempotency-Key`	`string`	A unique key (a UUID) for this request. Retrying with the same key and body returns the first result instead of repeating the work; the same key with a different body is a 409.

Request body

application/json · JobSubmitMultipleRequest

Request fields
Field	Type	Description
`jobs[]`required	`JobSubmitRequest[]`	List of job submission requests.
jobs.`job_name`required	`string`	Name of the job.
jobs.`job_type`required	`string`	Type of the job.
jobs.`payload`required	`object`	Job-specific parameters.
jobs.`resource`	`string`	The computational resource to be used for the job (e.g., "cpu", "a10", "h100"). Defaults to "default", which is job-specific. Default: `"default"`

Example request

curl -X POST "https://api.cognichem.com/api/v1/jobs/submit-multiple" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "jobs": [
    {
      "job_name": "catalog-admet-predict",
      "job_type": "admet-predict",
      "payload": {
        "input_data": [
          "CCO",
          "c1ccccc1"
        ],
        "input_format": "smiles",
        "thresholds": [
          {
            "endpoint": "admet_herg",
            "op": "lt",
            "value": 0.3
          }
        ]
      },
      "resource": "default"
    }
  ]
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.submit_many(
    [
        {
            "job_name": "catalog-admet-predict",
            "job_type": "admet-predict",
            "payload": {
                "input_data": ["CCO", "c1ccccc1"],
                "input_format": "smiles",
                "thresholds": [{"endpoint": "admet_herg", "op": "lt", "value": 0.3}],
            },
            "resource": "default",
        },
    ],
)
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY. The SDK sends an Idempotency-Key; pass idempotency_key= to reuse one when you retry.

Responses

Successful Response · application/json · JobSubmitMultipleResponse

Response fields
Field	Type	Description
`process_ids[]`	`string[]`	List of unique identifiers for the submitted jobs. Default: `[]`

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

List jobs

GET/api/v1/jobs/list

API key or token

List standalone Job Queue jobs for the current user.

Workflow step jobs (workflow_run_id set) are excluded from this default list. Paginated (limit/offset/total, cap 100). items carries full rows (status, type, timestamps, cost) so clients need not poll /jobs/status per job; job_names / job_pids remain for existing v1 clients.

Parameters

Query parameters
Name	Type	Description
`limit`	`integer`	Limits: `≥ 1, ≤ 100`
`offset`	`integer`	Limits: `≥ 0`
`status`	`string`	Comma-separated statuses to keep (e.g. `queued,running`). Limits: `max length 200`
`job_type`	`string`	Limits: `max length 100`
`q`	`string`	Case-insensitive job name search. Limits: `max length 200`
`sort`	`string`	`created_at`, `finished_at`, `runtime_seconds`, or `job_name`; prefix `-` for descending. Default `-created_at`. Limits: `max length 40`

Example request

curl "https://api.cognichem.com/api/v1/jobs/list" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.list()
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · ListJobsResponse

Response fields
Field	Type	Description
`items[]`	`JobListItem[]`	Same page as full rows (status, type, timestamps, cost). Default: `[]`
items.`charged_amount`	`number \| null`	Final charge (USD) once billed.
items.`created_at`	`string \| null`
items.`expected_billing_cost`	`number \| null`	Reservation estimate (USD).
items.`finished_at`	`string \| null`
items.`job_name`required	`string`	User-chosen job name.
items.`job_type`required	`string`	Catalog `job_type`.
items.`message`	`string`	Latest status message. Default: `""`
items.`process_id`required	`string`	Job process id.
items.`resource`required	`string`	Compute resource (`cpu`, `t4`, ...).
items.`result_artifact_id`	`string \| null`	Durable result artifact id, when stored.
items.`runtime_seconds`	`number`	Billed runtime so far. Default: `0`
items.`started_at`	`string \| null`
items.`status`required	`string`	Closed jobs-domain status. One of: `"queued", "dispatched", "running", "completed", "error", "cancelled"`
`job_names[]`	`string[]`	List of job names (parallel to `job_pids`; kept for v1 clients). Default: `[]`
`job_pids[]`	`string[]`	List of job process IDs. Default: `[]`
`limit`	`integer`	Default: `100`
`offset`	`integer`	Default: `0`
`total`	`integer`	Default: `0`

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Get job details

GET/api/v1/jobs/info

API key or token

Get detailed information about a specific job.

Parameters

Query parameters
Name	Type	Description
`process_id`required	`string`

Example request

curl "https://api.cognichem.com/api/v1/jobs/info?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.info("PROCESS_ID")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · JobInfoResponse

Response fields
Field	Type	Description
`info`required	`object`	A dictionary containing detailed information about the job, such as submission time, start time, end time, resource usage, etc.
`process_id`required	`string`	The unique identifier for the job process.

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Get job status

GET/api/v1/jobs/status

API key or token

Get the status of a submitted job.

Parameters

Query parameters
Name	Type	Description
`process_id`required	`string`

Example request

curl "https://api.cognichem.com/api/v1/jobs/status?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.status("PROCESS_ID")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · JobStatusResponse

Response fields
Field	Type	Description
`message`	`string \| null`	An optional message providing additional information about the job status.
`process_id`required	`string`	The unique identifier for the job process.
`result_artifact_id`	`string \| null`	Durable result artifact id when `public.jobs.result_artifact_id` is set. Agents should inspect / `?record=` this id instead of downloading whole-zip `GET /jobs/result`.
`status`required	`string`	Closed set from cognichem-jobs-domain: `queued\|dispatched\|running\|completed\|error\|cancelled`. One of: `"queued", "dispatched", "running", "completed", "error", "cancelled"`

Example 200 response

{
  "process_id": "fc-01HZXY9ABCDEF1234567890",
  "result_artifact_id": "art-01HZXY9ABCDEF1234567890",
  "status": "completed"
}

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Download a job result

GET/api/v1/jobs/result

API key or token

Get the result of a submitted job.

Parameters

Query parameters
Name	Type	Description
`process_id`required	`string`

Example request

curl "https://api.cognichem.com/api/v1/jobs/result?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.result("PROCESS_ID", save_path=".")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json

Response fields: any

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Download several job results

GET/api/v1/jobs/result-multiple

API key or token

Get the results of multiple submitted jobs.

Parameters

Query parameters
Name	Type	Description
`process_ids`required	`string`

Example request

curl "https://api.cognichem.com/api/v1/jobs/result-multiple?process_ids=PROCESS_IDS" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.result_many(["PROCESS_ID_1", "PROCESS_ID_2"], save_path=".")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json

Response fields: any

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Cancel a job

DELETE/api/v1/jobs/cancel

API key or token

Cancel a running job.

Parameters

Query parameters
Name	Type	Description
`process_id`required	`string`

Example request

curl -X DELETE "https://api.cognichem.com/api/v1/jobs/cancel?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.cancel("PROCESS_ID")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · MessageResponse

Response fields
Field	Type	Description
`message`required	`string`	The message content.

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Delete a job

DELETE/api/v1/jobs/delete

API key or token

Delete a job record from the user's job list.

Parameters

Query parameters
Name	Type	Description
`process_id`required	`string`

Example request

curl -X DELETE "https://api.cognichem.com/api/v1/jobs/delete?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.jobs.delete("PROCESS_ID")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · MessageResponse

Response fields
Field	Type	Description
`message`required	`string`	The message content.

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.