Run apps and manage tasks.

Run Task

POST /run

Run an app and optionally wait for completion.

Request

Field	Type	Required	Description
`app`	string	Yes	App identifier (`namespace/name@version`)
`input`	object	Yes	Input data matching app schema
`setup`	object	No	Setup parameters
`infra`	string	No	`"cloud"` or `"private"`
`workers`	string[]	No	Specific worker IDs
`webhook`	string	No	URL to receive a POST when the task completes
`session`	string	No	`"new"` to start a session, or existing session ID
`session_timeout`	number	No	Session idle timeout in seconds (1-3600, only with `session: "new"`)

Example:

json

1{2  "app": "infsh/flux",3  "input": {4    "prompt": "A sunset over mountains"5  },6  "setup": {7    "model": "schnell"8  }9}

Response

Field	Type	Description
`id`	string	Task ID
`status`	number	Status code
`input`	object	Input data
`output`	object	Output data (when complete)
`error`	string	Error message (if failed)
`session_id`	string	Session ID (if using sessions)
`created_at`	string	ISO timestamp

Example:

json

1{2  "id": "task_abc123",3  "status": 9,4  "input": { "prompt": "A sunset..." },5  "output": {6    "image": { "uri": "https://..." }7  },8  "created_at": "2024-01-15T10:30:00Z"9}

Get Task

GET /tasks/:id

Get task status and output.

Response

Same as Run Task response.

Example:

bash

1curl https://api.inference.sh/tasks/task_abc123 \2  -H "Authorization: Bearer inf_your_key"

Cancel Task

POST /tasks/:id/cancel

Cancel a running task.

Response

json

1{2  "id": "task_abc123",3  "status": 11,4  "cancelled": true5}

Task Status Codes

Status	Code	Description
Received	1	Task received
Queued	2	Waiting for worker
Scheduled	3	Assigned to worker
Preparing	4	Setting up environment
Serving	5	Loading model
Setting Up	6	Task initialization
Running	7	Executing
Uploading	8	Uploading results
Completed	9	Done
Failed	10	Error occurred
Cancelled	11	Cancelled

cURL Examples

Run and wait

bash

1curl -X POST https://api.inference.sh/run \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{5    "app": "infsh/flux",6    "input": {"prompt": "A sunset"}7  }'

Run without waiting

bash

1curl -X POST "https://api.inference.sh/run?wait=false" \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{5    "app": "infsh/flux",6    "input": {"prompt": "A sunset"}7  }'

Run with session

bash

1# Start a new session2curl -X POST https://api.inference.sh/run \3  -H "Authorization: Bearer inf_your_key" \4  -H "Content-Type: application/json" \5  -d '{6    "app": "my-app",7    "input": {"action": "init"},8    "session": "new"9  }'10# Response includes session_id: "sess_abc123"1112# Continue session13curl -X POST https://api.inference.sh/run \14  -H "Authorization: Bearer inf_your_key" \15  -H "Content-Type: application/json" \16  -d '{17    "app": "my-app",18    "input": {"action": "process"},19    "session": "sess_abc123"20  }'

Run with custom session timeout

bash

1# Start session with 5-minute idle timeout2curl -X POST https://api.inference.sh/run \3  -H "Authorization: Bearer inf_your_key" \4  -H "Content-Type: application/json" \5  -d '{6    "app": "my-app",7    "input": {"action": "init"},8    "session": "new",9    "session_timeout": 30010  }'

See Sessions Developer Guide for full documentation.

Webhooks

Get notified when a task completes by providing a webhook URL. When the task reaches a terminal state, a POST request is sent to your URL.

Run with webhook

bash

1curl -X POST https://api.inference.sh/run \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{5    "app": "infsh/flux",6    "input": {"prompt": "A sunset"},7    "webhook": "https://your-server.com/webhook"8  }'

Webhook payload

Your endpoint receives a JSON POST with the task result:

json

1{2  "id": "task_abc123",3  "status": 9,4  "output": { "image": { "uri": "https://..." } },5  "error": "",6  "session_id": null,7  "created_at": "2024-01-15T10:30:00Z",8  "updated_at": "2024-01-15T10:30:05Z"9}

Field	Type	Description
`id`	string	Task ID
`status`	number	Terminal status code (9=completed, 10=failed, 11=cancelled)
`output`	object	Task output (when completed)
`error`	string	Error message (when failed)
`session_id`	string	Session ID (if using sessions)
`created_at`	string	ISO timestamp
`updated_at`	string	ISO timestamp