jobs_get_status
Read-onlyIdempotent
Retrieve the status of a specific background job by its ID. Use this to check if a job completed, failed, or is still running.
Instructions
Fetch a specific background job status.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Implementation Reference
- src/mcp_template/modules/jobs.py:18-28 (handler)The tool handler function 'jobs_get_status' — registered as an MCP tool on the FastMCP server. Takes a job_id string, fetches status via the JobService, wraps KeyError as ValueError.
@server.tool( name="jobs_get_status", annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True, openWorldHint=False), ) async def jobs_get_status(job_id: str) -> object: """Fetch a specific background job status.""" with container.metrics.observe_tool("jobs_get_status"): try: return await container.jobs.get_status(job_id) except KeyError as exc: raise ValueError(str(exc)) from exc - The JobStatus Pydantic model returned by the handler — defines fields like id, status, progress, result, error.
class JobStatus(TemplateModel): id: str name: str status: Literal["queued", "running", "succeeded", "failed"] submitted_at: datetime started_at: datetime | None = None completed_at: datetime | None = None progress: float = 0.0 metadata: dict[str, Any] = Field(default_factory=dict) result: dict[str, Any] | None = None error: str | None = None - The JobService.get_status helper method that the handler delegates to — retrieves a deep copy of the JobStatus from the in-memory dict under an async lock.
async def get_status(self, job_id: str) -> JobStatus: async with self._lock: try: return self._jobs[job_id].model_copy(deep=True) except KeyError as exc: raise KeyError(f"Unknown job: {job_id}") from exc - src/mcp_template/modules/jobs.py:55-64 (registration)ModuleDescriptor returned by the register() function declaring the tool name 'jobs_get_status' in the tools list.
return ModuleDescriptor( name="jobs", title="Jobs", summary="Long-running task scaffolding and status resources for orchestration-heavy servers.", tags=["background", "async", "orchestration"], maturity="beta", tools=["jobs_submit_blueprint", "jobs_get_status", "jobs_list"], resources=["job://{job_id}"], prompts=["jobs_postmortem"], )