This tutorial explains how to retreive prediction data from the API.
## Retrieving Predictions
You can retrieve stored predictions using the `GET /api/v1/predictions` endpoint. This endpoint allows for flexible filtering based on several parameters.
### `GET /api/v1/predictions`
This endpoint retrieves prediction data based on the provided query parameters.
Authentication: Required.
Query Parameters:
- `metric` (string, required): The metric to retrieve. You can use "all" to get all metrics for the given filters. - `location_id` (UUID string, required): The ID of the location to get predictions for. - `stage` (string, optional): Filter by a specific prediction stage. - `source` (string, optional): Filter by a specific prediction source. - `from` (RFC3339 datetime string, optional): The start of the time range. Defaults to the current time. - `to` (RFC3339 datetime string, optional): The end of the time range. Defaults to 24 hours from the from time. - `limit` (integer, optional): The maximum number of predictions to return. The default is 1000, and the maximum is 10000.
Example Request:
curl "http://localhost:8000/api/v1/predictions?metric=mildew_risk&location_id=<location_id>&from=2023-10-27T00:00:00Z&to=2023-10-29T00:00:00Z" -H "Authorization: Bearer <your_token>"Response:
The API will respond with a JSON array of prediction objects that match the query.
## Potential errors and troubleshooting
This section lists likely error responses for the predictions endpoints, why they happen, and how to fix them.
- 400 Bad Request - Cause: Missing required query parameters (metric, location_id for GET). - How to resolve: Ensure required fields are present. Confirm query parameters are URL-encoded.
- 401 Unauthorized - Cause: Missing/invalid auth token. - How to resolve: Add a valid Authorization: Bearer <token> header. Verify token scope allows prediction operations.
- 403 Forbidden - Cause: Token does not have access to the requested organisation or resource. - How to resolve: Use credentials for the correct organisation or request elevated permissions.
- 404 Not Found - Cause: The referenced location_id does not exist or the specified metric/source is not recognized by the system in context. - How to resolve: Verify the location_id and other identifiers are correct. Use location listing endpoints if available.
- 429 Too Many Requests - Cause: Exceeding rate limits when sending many prediction queries. - How to resolve: Implement client-side rate limiting and exponential backoff.
- 500 Internal Server Error - Cause: Server-side failure while querying predictions (database errors). - How to resolve: Check server logs. If the issue persists, open an issue for the maintainers.