flexmeasures.api.v3_0.jobs

Classes

class flexmeasures.api.v3_0.jobs.JobAPI

Endpoint for querying the status of background jobs by UUID.

get_job_status(job_id: str, **kwargs)

— get:

summary: Get the status of a background job description: |

Look up a background job by its UUID and see whether it is queued, running, finished, or failed.

The response includes a status message plus job metadata such as the queue name, function name, timestamps, and the job result when available.

Failed jobs also include traceback information when the worker stored it with the job result.

For a finished scheduling job, result is an object. For a StorageScheduler job it holds soft state-of-charge constraint analysis: unresolved lists constraints the scheduler could not satisfy, and resolved lists constraints that were satisfied with some margin. Each device entry’s soc-minima/soc-maxima value is a list, holding one entry per violated slot (for unresolved) or per met slot with its margin (for resolved), ordered chronologically. Both arrays are empty when the flex model defines no soc-minima/soc-maxima, or when a scheduler other than StorageScheduler was used. The num-beliefs field holds the total number of beliefs (scheduled values) saved to the database. This is the only place constraint analysis is available — the sensor schedule endpoint (GET /api/v3_0/sensors/<id>/schedules/<uuid>) returns power values only.

security:

  • ApiKeyAuth: []

parameters:

  • in: path name: uuid required: true description: UUID of the background job. example: b3d26a8a-7a43-4a9f-93e1-fc2a869ea97b schema:

    type: string

responses:
200:

description: Finished job status retrieved successfully. content:

application/json:
schema:

type: object properties:

status:

type: string enum:

  • QUEUED

  • STARTED

  • FINISHED

  • FAILED

  • DEFERRED

  • SCHEDULED

  • STOPPED

  • CANCELED

description: Current status of the job.

message:

type: string description: Human-readable description of the job status.

result:
description: >

Return value of the job function, or null when not yet available. For a finished scheduling job, this is an object; a StorageScheduler job populates it with unresolved/resolved soft state-of-charge constraint analysis (empty arrays when the flex model defines no soc-minima/soc-maxima, or when a scheduler other than StorageScheduler was used). The num-beliefs field holds the total number of beliefs (scheduled values) saved to the database.

nullable: true

func-name:

type: string description: Fully-qualified name of the function executed by this job.

origin:

type: string description: Name of the queue the job was placed on.

enqueued-at:

type: string format: date-time nullable: true description: ISO-8601 timestamp of when the job was enqueued.

started-at:

type: string format: date-time nullable: true description: ISO-8601 timestamp of when the job started executing.

ended-at:

type: string format: date-time nullable: true description: ISO-8601 timestamp of when the job finished executing.

exc-info:

type: string nullable: true description: Traceback information for failed jobs, or null otherwise.

func_name:

type: string deprecated: true description: (DEPRECATED) Fully-qualified name of the function executed by this job. Use func-name instead.

enqueued_at:

type: string format: date-time nullable: true deprecated: true description: (DEPRECATED) ISO-8601 timestamp of when the job was enqueued. Use enqueued-at instead.

started_at:

type: string format: date-time nullable: true deprecated: true description: (DEPRECATED) ISO-8601 timestamp of when the job started executing. Use started-at instead.

ended_at:

type: string format: date-time nullable: true deprecated: true description: (DEPRECATED) ISO-8601 timestamp of when the job finished executing. Use ended-at instead.

exc_info:

type: string nullable: true deprecated: true description: (DEPRECATED) Traceback information for failed jobs, or null otherwise. Use exc-info instead.

deprecated-fields:

type: object description: Machine-readable mapping of deprecated fields with migration guidance.

examples:
queued:

summary: Queued job value:

status: QUEUED message: “Scheduling job waiting to be processed.” result: null func-name: “flexmeasures.data.services.scheduling.create_schedule” origin: scheduling enqueued-at: “2026-04-28T10:00:00+00:00” started-at: null ended-at: null exc-info: null func_name: “flexmeasures.data.services.scheduling.create_schedule” enqueued_at: “2026-04-28T10:00:00+00:00” started_at: null ended_at: null exc_info: null deprecated-fields:

func_name:

use: “func-name” deprecated-since: “1.0.0”

enqueued_at:

use: “enqueued-at” deprecated-since: “1.0.0”

started_at:

use: “started-at” deprecated-since: “1.0.0”

ended_at:

use: “ended-at” deprecated-since: “1.0.0”

exc_info:

use: “exc-info” deprecated-since: “1.0.0”

finished:

summary: Finished job value:

status: FINISHED message: “Scheduling job has finished.” result:

unresolved:

  • asset: 42 soc-minima:

    • datetime: “2024-01-01T10:00:00+00:00” violation: “260.0 kWh”

    • datetime: “2024-01-01T10:15:00+00:00” violation: “180.0 kWh”

resolved: [] num-beliefs: 96

func-name: “flexmeasures.data.services.scheduling.create_schedule” origin: scheduling enqueued-at: “2026-04-28T10:00:00+00:00” started-at: “2026-04-28T10:00:01+00:00” ended-at: “2026-04-28T10:00:05+00:00” exc-info: null

failed:

summary: Failed job value:

status: FAILED message: “Scheduling job failed with ValueError: …” result: null func-name: “flexmeasures.data.services.scheduling.create_schedule” origin: scheduling enqueued-at: “2026-04-28T10:00:00+00:00” started-at: “2026-04-28T10:00:01+00:00” ended-at: “2026-04-28T10:00:02+00:00” exc-info: “Traceback (most recent call last): …”

202:

description: Job is still queued, scheduled, deferred, or running.

422:

description: Job has failed.

404:

description: NOT_FOUND

401:

description: UNAUTHORIZED

403:

description: INVALID_SENDER

503:

description: SERVICE_UNAVAILABLE

tags:

  • Jobs