Submissions endpoint
List, create, fetch, and cancel submissions.
A submission is a job you ask Vilvik to run. The endpoint base path is https://beta.vilvik.com/api/v1/submissions/.
Using the Python SDK?
Every operation on this page is available on client.submissions. See Submissions.
List your submissions¶
GET /api/v1/submissions/?page_size=20
Returns a cursor-paginated array. Pass ?cursor=<value> (taken from the previous response) to get the next page.
curl -H "Authorization: Bearer $VILVIK_KEY" \
"https://beta.vilvik.com/api/v1/submissions/?page_size=20"
import vilvik
client = vilvik.Client()
page = client.submissions.list(limit=20)
for sub in page:
print(sub.id, sub.status, sub.name)
# every submission, cursors handled for you
for sub in client.submissions.iter_all(limit=50):
print(sub.id)
{
"results": [
{
"id": "abcDEF123456",
"name": "smoke test",
"status": "succeeded",
"source": "api",
"created_at": "2026-05-01T12:34:56Z"
}
],
"next": "?cursor=...",
"previous": null
}
Filtering by status, date range, name, and more is documented in Filtering submissions and results.
Required scope: submissions:read. See Submissions.
Create a submission¶
POST /api/v1/submissions/
Content-Type: application/json
The body carries the same parameters you would set in the website's new-submission form: num_generations, sol_per_pop, num_genes, num_parents_mating, init_range_low, init_range_high, fitness_func (a Python source string), and any optional callbacks.
Every code field needs a companion entry symbol: the top-level name in your source the runtime should call. Send it under <field>_entry, so inline fitness_func source pairs with fitness_func_entry, on_generation with on_generation_entry, and so on. The website auto-fills this from your code; over the API you set it yourself. A code field sent without its entry symbol is rejected with a 422.
curl -X POST https://beta.vilvik.com/api/v1/submissions/ \
-H "Authorization: Bearer $VILVIK_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "from script",
"num_generations": 100,
"num_parents_mating": 4,
"sol_per_pop": 10,
"num_genes": 5,
"init_range_low": -2,
"init_range_high": 2,
"fitness_func": "def fitness_func(ga, sol, idx):\n return sum(sol)\n",
"fitness_func_entry": "fitness_func"
}'
import vilvik
client = vilvik.Client()
submission = client.submissions.create(
name="from script",
num_generations=100,
num_parents_mating=4,
sol_per_pop=10,
num_genes=5,
init_range_low=-2,
init_range_high=2,
fitness_func=(
"def fitness_func(ga, sol, idx):\n"
" return sum(sol)\n"
),
fitness_func_entry="fitness_func",
)
print(submission.id, submission.status_url)
The response is 202 Accepted with the new id and URLs you can poll:
{
"id": "abcDEF123456",
"status": "queued",
"status_url": "https://beta.vilvik.com/api/v1/submissions/abcDEF123456",
"result_url": "https://beta.vilvik.com/api/v1/results/?submission_id=abcDEF123456"
}
The optional Idempotency-Key header lets you safely retry the same request without creating a duplicate submission. Use a fresh UUID per distinct submission. If the same key is reused within 24 hours, the server returns the original response instead of running the job again. The SDK sets one for you.
Required scope: submissions:write. See Submissions.
Fetch a single submission¶
GET /api/v1/submissions/<id>
Returns the full submission row, including current status and timing.
Required scope: submissions:read.
SDK equivalent: client.submissions.get(id). See Submissions.
Cancel or delete a submission¶
DELETE /api/v1/submissions/<id>
A single DELETE removes the submission. If it is still queued or running, the worker is stopped first, then the row is deleted. Credits already spent on a partial run are still billed. The response is 204 No Content.
curl -X DELETE https://beta.vilvik.com/api/v1/submissions/abcDEF123456 \
-H "Authorization: Bearer $VILVIK_KEY"
import vilvik
client = vilvik.Client()
client.submissions.delete("abcDEF123456")
Required scope: submissions:write. See Submissions.