Docs

Home All sections Swagger

Imports endpoint

Bring a local PyGAD experiment into Vilvik as an editable, continuable record.

Last updated June 3, 2026

The import endpoint lets you push the outcome of a PyGAD run you ran on your own machine into Vilvik. The result appears on your dashboard immediately, and you can edit the code or parameters and continue the run on Vilvik from where it ended.

Using the Python SDK?

A one-line helper vilvik.push(ga) is coming in a future SDK release. See Imports for a preview of the planned interface.

Create an import

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

Required scope: imports:write.

This endpoint is free. It does not consume credits.

Rate limits

Tier Per hour Per day
Free 10 50
Premium 60 300

Exceeding either limit returns 429 with error code rate_limited. Oversized payloads return 413 with error code payload_too_large.

Request body

{
  "name": "sphere min experiment",
  "ga_parameters": {
    "num_generations": 100,
    "sol_per_pop": 50,
    "num_genes": 5,
    "num_parents_mating": 4,
    "init_range_low": -2,
    "init_range_high": 2
  },
  "code": {
    "fitness_func": "def fitness_func(ga, sol, idx):\n    return -sum(s*s for s in sol)\n",
    "on_generation": "def on_generation(ga):\n    pass\n"
  },
  "result": {
    "best_solution": [0.01, -0.02, 0.005, 0.003, -0.01],
    "best_solution_fitness": -0.00059,
    "best_solutions_fitness": [-4.2, -2.1, -0.8, -0.3, -0.001],
    "generations_completed": 100,
    "best_solution_generation": 98,
    "population": [[0.01, -0.02, 0.005, 0.003, -0.01]]
  },
  "origin": {
    "sdk_version": "3.3.1",
    "python_version": "3.12.0"
  }
}

Fields

Field Required What it is
name No Display name shown on the dashboard.
ga_parameters Yes Object holding the GA configuration. Must include num_generations. Any other PyGAD parameter is accepted.
code Yes Object holding the Python source strings.
code.fitness_func Yes Source of the fitness function.
code.on_start No Source of the on_start callback.
code.on_fitness No Source of the on_fitness callback.
code.on_parents No Source of the on_parents callback.
code.on_crossover No Source of the on_crossover callback.
code.on_mutation No Source of the on_mutation callback.
code.on_generation No Source of the on_generation callback.
code.on_stop No Source of the on_stop callback.
code.<name>_entry No Alternate entry-point name for the matching callback (for example on_generation_entry).
result Yes Object holding the outcome of your run.
result.best_solution Yes The best solution vector found.
result.best_solution_fitness Yes Fitness of the best solution.
result.best_solutions_fitness Yes Fitness of the best solution at the end of each generation.
result.generations_completed Yes Number of generations the run completed.
result.best_solution_generation Yes Generation at which the best solution was found.
result.population No The final population. Include this if you want to continue the run on Vilvik from the exact state where your local run ended.
result.last_generation_fitness No Fitness values of every individual in the last generation.
origin No Free-form object with information about the client that created the import (SDK version, Python version, etc.).

Example request

curl -X POST https://beta.vilvik.com/api/v1/imports/ \
  -H "Authorization: Bearer vlk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sphere min experiment",
    "ga_parameters": {
      "num_generations": 100,
      "sol_per_pop": 50,
      "num_genes": 5,
      "num_parents_mating": 4,
      "init_range_low": -2,
      "init_range_high": 2
    },
    "code": {
      "fitness_func": "def fitness_func(ga, sol, idx):\n    return -sum(s*s for s in sol)\n"
    },
    "result": {
      "best_solution": [0.01, -0.02, 0.005, 0.003, -0.01],
      "best_solution_fitness": -0.00059,
      "best_solutions_fitness": [-4.2, -2.1, -0.8, -0.3, -0.001],
      "generations_completed": 100,
      "best_solution_generation": 98
    }
  }'

Response

A successful import returns 201 Created:

{
  "id": "abcDEF123456",
  "result_id": "JKLmnop789",
  "result_url": "https://vilvik.com/app/result/JKLmnop789/"
}
Field What it is
id The id of the new submission record.
result_id The id of the result created from your import data.
result_url Direct link to the result page on the dashboard.

Imported badge

An imported result is marked with an "Imported" badge on the dashboard and in the API response. The badge stays until you re-run the submission on Vilvik, at which point the result is replaced with a verified run.

Thanks for the feedback!