Yookr Logo

Prediction Ingestion Guide

Learn how to implement workers that process jobs and push results into the system.

This guide provides everything you need to know about pushing prediction data from your workers into the Prediction API.

Table of Contents

The Ingestion Process

The prediction ingestion process typically involves three high-level steps:

1. Retrieving Jobs: Fetching active jobs that define what predictions your model needs to make. 2. Processing: Fetching external telemetry (e.g., weather forecasts) based on the job. 3. Submission: Posting the calculated results back to the API.

Tip

Looking to view prediction results?

If you want to query or visualize stored predictions instead of submitting them, please see the Retrieving Predictions guide.

Step 1: Fetching Configuration

To build a configurable worker, you first fetch the list of "Jobs" assigned to your service version. This tells your worker which physical hardware IDs it needs to query.

GET /api/v1/jobs/service/{service_id}

Retrieves all active jobs for a specific version.

  • Authentication: Required.
  • Path Parameter: service_id (This is your Source Version ID found in the Job Setup result).

Example Request:

bash
curl "http://localhost:8000/api/v1/jobs/service/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <your_token>"

Step 2: Creating Predictions

Once your logic has calculated the results, you submit them in batches to the ingestion pipeline.

POST /api/v1/predictions

Submit a batch of prediction targets.

Request Body (Job-Based):

json
{
  "job_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "service_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
  "run_at": "2023-10-27T10:00:00Z",
  "predictions": [
    {
      "datetime_measure": "2023-10-27T12:00:00Z",
      "targets": [
        {
          "target_id": "target-uuid-1",
          "value_num": 18.5,
          "confidence": 0.95
        }
      ]
    }
  ]
}
  • run_at: When your model was executed.
  • datetime_measure: The specific point in time the prediction is for.
  • target_id: The ID of the virtual sensor assigned during setup.

Retention and Cleanup

To optimize storage, the Prediction API automatically purges old data based on the Retention (hours) setting defined at the Source level.

The Cleanup Logic

Cleanup is performed relative to datetime_measure, the time the prediction is for. A prediction becomes eligible for deletion after that measured time plus the model's retention period. Deletion happens only when a cleanup job runs, so eligible records may remain a little longer.

Important

Retention example

A prediction made on 11 August 2026 for 25 August 2026 at 06:00, with 24-hour retention, becomes eligible for deletion from 26 August 2026 at 06:00. It is deleted when a cleanup job next runs.

Implementation Strategy

Why do we "Retrieve Jobs" instead of hardcoding sensor IDs?

To keep your prediction workers decoupled from hardware deployments, workers should not be hardcoded with specific IDs. Instead:

  • Use the Job Setup guide to map abstract Roles (like "ambient_temperature") to physical IDs.
  • The worker asks the API: "What jobs am I supposed to run?".
  • The API returns a list of Job Role Bindings containing the physical IDs.

This allows you to update the input sensors in the UI without ever touching the worker code.

Language Tutorials

For production-grade implementation examples, please see: