> ## Documentation Index
> Fetch the complete documentation index at: https://premlabs-fix-example-pdf.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# JSONL Dataset Workflow

> Upload a JSONL dataset, create snapshots, and launch fine-tuning jobs.

<Note>
  Export your Prem API key as `API_KEY` before running any script.
</Note>

<Steps>
  <Step>
    # Setup: Define your JSONL file

    <CodeGroup>
      ```ts TypeScript theme={null}
      const API_KEY = process.env.API_KEY;

      // Define your JSONL dataset file
      const JSONL_FILE_PATH = 'sample_data.jsonl';
      ```

      ```python Python theme={null}
      import os
      import time
      import requests

      API_KEY = os.getenv("API_KEY")

      # Define your JSONL dataset file
      JSONL_FILE_PATH = "sample_data.jsonl"
      ```
    </CodeGroup>

    Define the path to your JSONL dataset file. Make sure the file exists and is properly formatted.
  </Step>

  <Step>
    # Create a project

    <CodeGroup>
      ```ts TypeScript theme={null}
      const res = await fetch('https://studio.premai.io/api/v1/public/projects/create', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ name: 'Test Project', goal: 'Test finetuning' })
      });
      if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
      const { project_id } = await res.json();
      ```

      ```python Python theme={null}
      response = requests.post(
          "https://studio.premai.io/api/v1/public/projects/create",
          headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
          json={"name": "Test Project", "goal": "Test finetuning"}
      )
      response.raise_for_status()
      project_id = response.json()["project_id"]
      ```
    </CodeGroup>

    Start by creating a project workspace. The `project_id` is required for all subsequent operations.
  </Step>

  <Step>
    # Upload JSONL dataset

    <CodeGroup>
      ```ts TypeScript theme={null}
      const formData = new FormData();
      formData.append('project_id', project_id);
      formData.append('name', 'Test Dataset');
      const jsonlFile = file(JSONL_FILE_PATH);
      formData.append('file', jsonlFile, JSONL_FILE_PATH);

      const res = await fetch('https://studio.premai.io/api/v1/public/datasets/create-from-jsonl', {
        method: 'POST',
        headers: { 'Authorization': `Bearer ${API_KEY}` },
        body: formData
      });
      if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
      const { dataset_id } = await res.json();
      ```

      ```python Python theme={null}
      with open(JSONL_FILE_PATH, 'rb') as f:
          files = {'file': (JSONL_FILE_PATH, f, 'application/json')}
          data = {'project_id': project_id, 'name': 'Test Dataset'}
          response = requests.post(
              "https://studio.premai.io/api/v1/public/datasets/create-from-jsonl",
              headers={"Authorization": f"Bearer {API_KEY}"},
              files=files,
              data=data
          )
      response.raise_for_status()
      dataset_id = response.json()["dataset_id"]
      ```
    </CodeGroup>

    Upload your pre-formatted JSONL file. Each line should contain a chat conversation in the expected format. For details on the required dataset structure, see [Dataset Structure](/datasets/overview#dataset-structure).
  </Step>

  <Step>
    # Wait for dataset processing

    <CodeGroup>
      ```ts TypeScript theme={null}
      let dataset;
      do {
        await sleep(2000);
        const res = await fetch(`https://studio.premai.io/api/v1/public/datasets/${dataset_id}`, {
          headers: { 'Authorization': `Bearer ${API_KEY}` }
        });
        if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
        dataset = await res.json();
      } while (dataset.status === 'processing');
      ```

      ```python Python theme={null}
      while True:
          time.sleep(2)
          response = requests.get(
              f"https://studio.premai.io/api/v1/public/datasets/{dataset_id}",
              headers={"Authorization": f"Bearer {API_KEY}"}
          )
          response.raise_for_status()
          dataset = response.json()
          if dataset["status"] != "processing":
              break
      ```
    </CodeGroup>

    Poll the dataset status until processing completes. JSONL uploads are typically fast.
  </Step>

  <Step>
    # Create snapshot

    <CodeGroup>
      ```ts TypeScript theme={null}
      const res = await fetch('https://studio.premai.io/api/v1/public/snapshots/create', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ dataset_id, split_percentage: 80 })
      });
      if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
      const { snapshot_id } = await res.json();
      ```

      ```python Python theme={null}
      response = requests.post(
          "https://studio.premai.io/api/v1/public/snapshots/create",
          headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
          json={"dataset_id": dataset_id, "split_percentage": 80}
      )
      response.raise_for_status()
      snapshot_id = response.json()["snapshot_id"]
      ```
    </CodeGroup>

    Split the dataset into training and validation sets. The default 80/20 split works well for most cases.
  </Step>

  <Step>
    # Generate recommendations

    <CodeGroup>
      ```ts TypeScript theme={null}
      const res = await fetch('https://studio.premai.io/api/v1/public/recommendations/generate', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ snapshot_id })
      });
      if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);

      let recs;
      do {
        await sleep(5000);
        const res2 = await fetch(`https://studio.premai.io/api/v1/public/recommendations/${snapshot_id}`, {
          headers: { 'Authorization': `Bearer ${API_KEY}` }
        });
        if (!res2.ok) throw new Error(`${res2.status}: ${await res2.text()}`);
        recs = await res2.json();
      } while (recs.status === 'processing');
      ```

      ```python Python theme={null}
      response = requests.post(
          "https://studio.premai.io/api/v1/public/recommendations/generate",
          headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
          json={"snapshot_id": snapshot_id}
      )
      response.raise_for_status()

      while True:
          time.sleep(5)
          response = requests.get(
              f"https://studio.premai.io/api/v1/public/recommendations/{snapshot_id}",
              headers={"Authorization": f"Bearer {API_KEY}"}
          )
          response.raise_for_status()
          recs = response.json()
          if recs["status"] != "processing":
              break
      ```
    </CodeGroup>

    Request model recommendations for your snapshot. Poll until recommendations are ready, then filter for recommended models.
  </Step>

  <Step>
    # Create fine-tuning job

    <CodeGroup>
      ```ts TypeScript theme={null}
      const experiments = recs.recommended_experiments
        .filter((e: any) => e.recommended)
        .map(({ recommended, reason_for_recommendation, ...experiment }: any) => experiment);

      const res = await fetch('https://studio.premai.io/api/v1/public/finetuning/create', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ snapshot_id, name: 'Test Job', experiments })
      });
      if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
      const { job_id } = await res.json();
      ```

      ```python Python theme={null}
      experiments = [
          {k: v for k, v in exp.items() if k not in ["recommended", "reason_for_recommendation"]}
          for exp in recs["recommended_experiments"] if exp["recommended"]
      ]

      response = requests.post(
          "https://studio.premai.io/api/v1/public/finetuning/create",
          headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
          json={"snapshot_id": snapshot_id, "name": "Test Job", "experiments": experiments}
      )
      response.raise_for_status()
      job_id = response.json()["job_id"]
      ```
    </CodeGroup>

    Filter recommended experiments and use them directly to launch the fine-tuning job.
  </Step>

  <Step>
    # Monitor job progress

    <CodeGroup>
      ```ts TypeScript theme={null}
      for (let i = 0; i < 30; i++) {
        await sleep(10000);
        const res = await fetch(`https://studio.premai.io/api/v1/public/finetuning/${job_id}`, {
          headers: { 'Authorization': `Bearer ${API_KEY}` }
        });
        if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
        const job = await res.json();
        console.log(`Status: ${job.status}`);
        job.experiments.forEach((e: any) => {
          console.log(`  - Exp #${e.experiment_number}: ${e.status} ${e.model_id || ''}`);
        });
        if (job.status !== 'processing') break;
      }
      ```

      ```python Python theme={null}
      for i in range(30):
          time.sleep(10)
          response = requests.get(
              f"https://studio.premai.io/api/v1/public/finetuning/{job_id}",
              headers={"Authorization": f"Bearer {API_KEY}"}
          )
          response.raise_for_status()
          job = response.json()
          print(f"Status: {job['status']}")
          for exp in job["experiments"]:
              print(f"  - Exp #{exp['experiment_number']}: {exp['status']} {exp.get('model_id', '')}")
          if job["status"] != "processing":
              break
      ```
    </CodeGroup>

    Poll the job status every 10 seconds. Each experiment shows its status and final model ID when complete.
  </Step>
</Steps>

## Full Example

<CodeGroup>
  ```ts TypeScript theme={null}
  #!/usr/bin/env bun

  /**
   * Example 1: JSONL dataset workflow
   * 1. Create project → 2. Upload JSONL → 3. Create snapshot → 4. Get recommendations → 5. Run finetuning
   */

  import { file } from 'bun';

  const API_KEY = process.env.API_KEY;
  const JSONL_FILE_PATH = 'sample_data.jsonl';

  if (!API_KEY) {
  	console.error('Error: API_KEY environment variable is required');
  	console.error('Please create a .env file based on .env.example');
  	process.exit(1);
  }

  function sleep(ms: number) {
  	return new Promise((r) => setTimeout(r, ms));
  }

  async function main() {
  	console.log('\n=== JSONL Workflow ===\n');

  	// 1. Create project
  	console.log('1. Creating project...');
  	const res1 = await fetch('https://studio.premai.io/api/v1/public/projects/create', {
  		method: 'POST',
  		headers: {
  			'Authorization': `Bearer ${API_KEY}`,
  			'Content-Type': 'application/json'
  		},
  		body: JSON.stringify({ name: 'Test Project', goal: 'Test finetuning' }),
  	});
  	if (!res1.ok) throw new Error(`${res1.status}: ${await res1.text()}`);
  	const { project_id } = await res1.json();
  	console.log(`   ✓ Project: ${project_id}\n`);

  	// 2. Upload JSONL
  	console.log('2. Uploading JSONL dataset...');
  	const formData = new FormData();
  	formData.append('project_id', project_id);
  	formData.append('name', 'Test Dataset');
  	const jsonlFile = file(JSONL_FILE_PATH);
  	formData.append('file', jsonlFile, JSONL_FILE_PATH);

  	const res2 = await fetch('https://studio.premai.io/api/v1/public/datasets/create-from-jsonl', {
  		method: 'POST',
  		headers: { 'Authorization': `Bearer ${API_KEY}` },
  		body: formData,
  	});
  	if (!res2.ok) throw new Error(`${res2.status}: ${await res2.text()}`);
  	const { dataset_id } = await res2.json();
  	console.log(`   ✓ Dataset: ${dataset_id}`);

  	// Wait for dataset
  	console.log('   Waiting for dataset...');
  	let dataset;
  	do {
  		await sleep(2000);
  		const res = await fetch(`https://studio.premai.io/api/v1/public/datasets/${dataset_id}`, {
  			headers: { 'Authorization': `Bearer ${API_KEY}` }
  		});
  		if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  		dataset = await res.json();
  	} while (dataset.status === 'processing');
  	console.log(`   ✓ Ready: ${dataset.datapoints_count} datapoints\n`);

  	// 3. Create snapshot
  	console.log('3. Creating snapshot...');
  	const res3 = await fetch('https://studio.premai.io/api/v1/public/snapshots/create', {
  		method: 'POST',
  		headers: {
  			'Authorization': `Bearer ${API_KEY}`,
  			'Content-Type': 'application/json'
  		},
  		body: JSON.stringify({ dataset_id, split_percentage: 80 }),
  	});
  	if (!res3.ok) throw new Error(`${res3.status}: ${await res3.text()}`);
  	const { snapshot_id } = await res3.json();
  	console.log(`   ✓ Snapshot: ${snapshot_id}\n`);

  	// 4. Generate recommendations
  	console.log('4. Generating recommendations...');
  	const res4 = await fetch('https://studio.premai.io/api/v1/public/recommendations/generate', {
  		method: 'POST',
  		headers: {
  			'Authorization': `Bearer ${API_KEY}`,
  			'Content-Type': 'application/json'
  		},
  		body: JSON.stringify({ snapshot_id }),
  	});
  	if (!res4.ok) throw new Error(`${res4.status}: ${await res4.text()}`);

  	let recs;
  	do {
  		await sleep(5000);
  		const res = await fetch(`https://studio.premai.io/api/v1/public/recommendations/${snapshot_id}`, {
  			headers: { 'Authorization': `Bearer ${API_KEY}` }
  		});
  		if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  		recs = await res.json();
  	} while (recs.status === 'processing');

  	console.log(`   ✓ Recommended experiments:`);
  	const recommendedCount = recs.recommended_experiments.filter((e: any) => e.recommended).length;
  	console.log(`   Total experiments: ${recs.recommended_experiments.length}, Recommended: ${recommendedCount}`);
  	recs.recommended_experiments.forEach((e: any) => {
  		if (e.recommended) console.log(`     - ${e.base_model_id} (LoRA: ${e.lora})`);
  	});
  	console.log();

  	// 5. Create finetuning job
  	console.log('5. Creating finetuning job...');
  	const experiments = recs.recommended_experiments
  		.filter((e: any) => e.recommended)
  		.map(({ recommended, reason_for_recommendation, ...experiment }: any) => experiment);

  	if (experiments.length === 0) {
  		console.error('\n✗ Error: No recommended experiments found. Cannot create finetuning job.');
  		process.exit(1);
  	}

  	const res5 = await fetch('https://studio.premai.io/api/v1/public/finetuning/create', {
  		method: 'POST',
  		headers: {
  			'Authorization': `Bearer ${API_KEY}`,
  			'Content-Type': 'application/json'
  		},
  		body: JSON.stringify({ snapshot_id, name: 'Test Job', experiments }),
  	});
  	if (!res5.ok) throw new Error(`${res5.status}: ${await res5.text()}`);
  	const { job_id } = await res5.json();
  	console.log(`   ✓ Job: ${job_id}\n`);

  	// 6. Monitor (5 minutes max)
  	console.log('6. Monitoring job...');
  	for (let i = 0; i < 30; i++) {
  		await sleep(10000);
  		const res = await fetch(`https://studio.premai.io/api/v1/public/finetuning/${job_id}`, {
  			headers: { 'Authorization': `Bearer ${API_KEY}` }
  		});
  		if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  		const job = await res.json();
  		console.log(`   Status: ${job.status}`);
  		job.experiments.forEach((e: any) => {
  			console.log(`     - Exp #${e.experiment_number}: ${e.status} ${e.model_id || ''}`);
  		});
  		if (job.status !== 'processing') break;
  	}

  	console.log('\n✓ Done!\n');
  }

  main().catch((err) => {
  	console.error('\n✗ Error:', err.message);
  	process.exit(1);
  });
  ```

  ```python Python theme={null}
  #!/usr/bin/env python3

  """
  Example 1: JSONL dataset workflow
  1. Create project → 2. Upload JSONL → 3. Create snapshot → 4. Get recommendations → 5. Run finetuning
  """

  import os
  import time
  import requests

  API_KEY = os.getenv("API_KEY")
  JSONL_FILE_PATH = "sample_data.jsonl"

  if not API_KEY:
      print("Error: API_KEY environment variable is required")
      exit(1)


  def api(endpoint: str, method: str = "GET", **kwargs):
      response = requests.request(
          method=method,
          url=f"https://studio.premai.io{endpoint}",
          headers={"Authorization": f"Bearer {API_KEY}", **kwargs.pop("headers", {})},
          **kwargs
      )
      if not response.ok:
          err = response.json() if response.content else {}
          error_msg = err.get("error", str(err)) if isinstance(err, dict) else str(err)
          raise Exception(f"{response.status_code}: {error_msg}")
      return response.json()


  def main():
      print("\n=== JSONL Workflow ===\n")

      #  Create project
      print("1. Creating project...")
      result = api("/api/v1/public/projects/create", method="POST", headers={"Content-Type": "application/json"}, json={"name": "Test Project", "goal": "Test finetuning"})
      project_id = result["project_id"]
      print(f"   ✓ Project: {project_id}\n")

      #  Upload JSONL
      print("2. Uploading JSONL dataset...")
      with open(JSONL_FILE_PATH, "rb") as f:
          files = {"file": (JSONL_FILE_PATH, f, "application/json")}
          data = {"project_id": project_id, "name": "Test Dataset"}
          result = api("/api/v1/public/datasets/create-from-jsonl", method="POST", files=files, data=data)
      dataset_id = result["dataset_id"]
      print(f"   ✓ Dataset: {dataset_id}")

      # Wait for dataset
      print("   Waiting for dataset...")
      while True:
          time.sleep(2)
          dataset = api(f"/api/v1/public/datasets/{dataset_id}")
          if dataset["status"] != "processing":
              break
      print(f"   ✓ Ready: {dataset['datapoints_count']} datapoints\n")

      #  Create snapshot
      print("3. Creating snapshot...")
      result = api("/api/v1/public/snapshots/create", method="POST", headers={"Content-Type": "application/json"}, json={"dataset_id": dataset_id, "split_percentage": 80})
      snapshot_id = result["snapshot_id"]
      print(f"   ✓ Snapshot: {snapshot_id}\n")

      #  Generate recommendations
      print("4. Generating recommendations...")
      api("/api/v1/public/recommendations/generate", method="POST", headers={"Content-Type": "application/json"}, json={"snapshot_id": snapshot_id})

      while True:
          time.sleep(5)
          recs = api(f"/api/v1/public/recommendations/{snapshot_id}")
          if recs["status"] != "processing":
              break

      print("   ✓ Recommended experiments:")
      recommended_count = sum(1 for e in recs["recommended_experiments"] if e["recommended"])
      print(f"   Total experiments: {len(recs['recommended_experiments'])}, Recommended: {recommended_count}")
      for e in recs["recommended_experiments"]:
          if e["recommended"]:
              print(f"     - {e['base_model_id']} (LoRA: {e['lora']})")
      print()

      #  Create finetuning job
      print("5. Creating finetuning job...")
      experiments = [
          {k: v for k, v in exp.items() if k not in ["recommended", "reason_for_recommendation"]}
          for exp in recs["recommended_experiments"] if exp["recommended"]
      ]

      if not experiments:
          print("\n✗ Error: No recommended experiments found. Cannot create finetuning job.")
          exit(1)

      result = api("/api/v1/public/finetuning/create", method="POST", headers={"Content-Type": "application/json"}, json={"snapshot_id": snapshot_id, "name": "Test Job", "experiments": experiments})
      job_id = result["job_id"]
      print(f"   ✓ Job: {job_id}\n")

      #  Monitor (5 minutes max)
      print("6. Monitoring job...")
      for i in range(30):
          time.sleep(10)
          job = api(f"/api/v1/public/finetuning/{job_id}")
          print(f"   Status: {job['status']}")
          for exp in job["experiments"]:
              print(f"     - Exp #{exp['experiment_number']}: {exp['status']} {exp.get('model_id', '')}")
          if job["status"] != "processing":
              break

      print("\n✓ Done!\n")


  if __name__ == "__main__":
      try:
          main()
      except Exception as err:
          print(f"\n✗ Error: {err}")
          exit(1)
  ```
</CodeGroup>