Documentation Index
Fetch the complete documentation index at: https://mintlify.com/timepoint-ai/timepoint-clockchain/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Use this endpoint to check the status of a generation job created via the Generate or Bulk Generate endpoints.
Authentication
Requires SERVICE_API_KEY header for authentication.
X-Service-Key: your-service-api-key
Path Parameters
The unique job identifier returned from the generate endpoint.
Response
The job’s unique identifier.
Current processing status.Job States:
pending - Job queued, not yet startedprocessing - Currently generating moment via Flash APIcompleted - Successfully generated and indexed to graphfailed - Generation or indexing failed
Full graph path where the moment is indexed. Only populated when status is completed.Format: /YYYY/month/DD/HHMM/country/region/city/event-slugExample: /1776/july/04/1200/united-states/pennsylvania/philadelphia/signing-declaration-independence-3f4a
Detailed error message if status is failed. Includes Flash API response details when available.
ISO 8601 timestamp when the job was created.
ISO 8601 timestamp when the job finished processing (success or failure). null while pending or processing.
Example Request
curl -X GET https://api.clockchain.io/api/jobs/a3d8f7e2-4c1b-4a9e-8f2d-1e3c5b7a9d0f \
-H "X-Service-Key: your-service-api-key"
Example Response (Pending)
{
"job_id": "a3d8f7e2-4c1b-4a9e-8f2d-1e3c5b7a9d0f",
"status": "pending",
"path": null,
"error": null,
"created_at": "2026-03-06T14:32:18.123456Z",
"completed_at": null
}
Example Response (Processing)
{
"job_id": "a3d8f7e2-4c1b-4a9e-8f2d-1e3c5b7a9d0f",
"status": "processing",
"path": null,
"error": null,
"created_at": "2026-03-06T14:32:18.123456Z",
"completed_at": null
}
Example Response (Completed)
{
"job_id": "a3d8f7e2-4c1b-4a9e-8f2d-1e3c5b7a9d0f",
"status": "completed",
"path": "/1776/july/04/1200/united-states/pennsylvania/philadelphia/signing-declaration-independence-3f4a",
"error": null,
"created_at": "2026-03-06T14:32:18.123456Z",
"completed_at": "2026-03-06T14:32:32.987654Z"
}
Example Response (Failed)
{
"job_id": "a3d8f7e2-4c1b-4a9e-8f2d-1e3c5b7a9d0f",
"status": "failed",
"path": null,
"error": "Flash API error: Invalid date format | response: {\"detail\":\"Year must be a valid integer\"}",
"created_at": "2026-03-06T14:32:18.123456Z",
"completed_at": "2026-03-06T14:32:25.456789Z"
}
Polling Best Practices
Recommended polling strategy:
- Poll every 2 seconds for the first 30 seconds
- Increase to 5-second intervals afterward
- Set a maximum timeout (e.g., 2 minutes)
- Exponential backoff for production systems
Understanding Job States
Pending
The job has been created and added to the queue but hasn’t started processing yet. This state is usually very brief.
Processing
The job is actively:
- Calling the Flash Timepoint API with the query
- Parsing the Flash response
- Extracting structured data (date, location, figures, etc.)
- Building the graph path
- Indexing the node into the Clockchain graph
Completed
The moment has been successfully generated and indexed. The path field contains the location in the graph where you can retrieve the full moment details.
Failed
Generation failed at some stage. Check the error field for details. Common failure reasons:
- Flash API errors (invalid date, ambiguous event, rate limits)
- Network timeouts
- Invalid query format
- Graph indexing errors
Jobs are stored in memory. If the service restarts, job history may be lost. For production use, implement job result persistence or save the path immediately when status becomes completed.
Error Responses
| Status Code | Description |
|---|
| 404 | Job ID not found |
| 401 | Missing or invalid SERVICE_API_KEY |
| 503 | Job manager not available |
Next Steps
Once a job is completed:
- Use the
path to fetch full moment details via /api/moments/{path}
- Publish the moment to make it publicly visible
- Query connected moments via the graph API