> ## Documentation Index > Fetch the complete documentation index at: https://docs.plantpredict.com/llms.txt > Use this file to discover all available pages before exploring further. # List predictions for a project > Returns all predictions for a project. Predictions do not include power plant data; use the Power Plant operation for sub-entities. **Parameters:** - `projectId` (path, required): The project ID. ## OpenAPI ````yaml /api-docs/api-reference/plantpredict-api.yaml get /Project/{projectId}/Prediction openapi: 3.1.0 info: title: PlantPredict API version: 12.13.0 description: > ## What is PlantPredict? PlantPredict is an industry-leading performance modeling platform for utility-scale solar power plants. It predicts energy yield across the full project lifecycle — from early-stage site prospecting through detailed engineering and operational monitoring. The same engine that powers the PlantPredict web UI is fully exposed via this REST API, enabling automation of complex, high-time-resolution energy predictions without any UI interaction. ## Domain Model — read this first Understanding the object hierarchy is essential before calling the API: - **Weather** — A weather file (hourly irradiance, temperature, wind, etc.) for a geographic location. Imported from a provider (e.g. SolarAnywhere, Meteonorm) or uploaded manually. Weather files live in a company-wide library and are referenced by Predictions. - **Module** — A PV module definition parameterized with electrical characteristics (STC power, temperature coefficients, single-diode model parameters, IAM curves, etc.). Modules live in a company-wide library. - **Inverter** — An inverter definition with efficiency curves, voltage/power ratings, and optional kVA derating curves. Inverters live in a company-wide library. - **Project** — A named location (lat/lon) that acts as a container for one or more Predictions. Holds geographic metadata (country, elevation, UTC offset) and a status. - **Prediction** — The core simulation configuration nested under a Project. Defines the simulation period, model selections (transposition, air mass, degradation, soiling, shading, spectral shift models), uncertainty error terms, and references to a Weather file. A Prediction must be linked to a PowerPlant before it can be run. Status values: 0 = Draft, 1 = Active, 2 = Issued, 3 = Archived. - **PowerPlant** — The physical plant design attached to a Prediction. Describes the electrical topology: Blocks → Arrays → Inverters → DC Fields (strings of modules). Also includes transformers, transmission lines, energy storage (ESS), availability losses, and LGIA export limits. - **Shade Scene** — An optional 3D shading model (PVJ format) attached to a Prediction's DC Fields. Supports import from PVC or SHD files. Shade and TABT (Tracker Angle Back-Tracking) calculations are queued and run asynchronously. ## Typical workflow to run a prediction 1. Ensure a **Weather** file exists (search, download, or import one). 2. Ensure a **Module** and **Inverter** exist in the library. 3. **POST /Project** — create a project at the site location. 4. **POST /Project/{projectId}/Prediction** — create a prediction with model settings. 5. **POST /Project/{projectId}/Prediction/{predictionId}/PowerPlant** — attach a plant design referencing your module and inverter. 6. **POST /Project/{projectId}/Prediction/{predictionId}/Run** — queue the simulation. 7. Poll **GET /Project/{projectId}/Prediction/{predictionId}/Overview** until `status` reaches 2 (complete), then retrieve results via `/ResultSummary`, `/ResultDetails`, or `/NodalJson`. ## Authentication OAuth 2.0 **Client Credentials** flow via AWS Cognito. The spec advertises a single `bearerAuth` scheme — fetch a token yourself with the snippet below, then either paste it into the in-browser playground or pass it on every request as `Authorization: Bearer `. > **Why not advertise OAuth2 directly?** Most users have access to the > production tenant only, and we don't want to invite anyone to enter > long-lived `client_id` / `client_secret` credentials into a third-party > documentation site. Keep credentials in your own environment; ship > short-lived bearer tokens to wherever they are needed. - Token URL: `https://terabase-prd.auth.us-west-2.amazoncognito.com/oauth2/token` - Scopes: `transactions/get` (read), `transactions/post` (write) — request both to access the entire surface. - Send credentials as **Basic Auth** in the token request header. Example: ```bash curl -X POST 'https://terabase-prd.auth.us-west-2.amazoncognito.com/oauth2/token' \ -u "$PP_CLIENT_ID:$PP_CLIENT_SECRET" \ -d 'grant_type=client_credentials&scope=transactions/get transactions/post' ``` API credentials (Client ID + Secret) are generated per user by a company admin inside the PlantPredict UI (gear icon → user profile → Generate API Credentials). Store them securely — they are shown only once. ## Notes - All request/response bodies are JSON (`Content-Type: application/json`). - The API is stateless — every request must supply complete inputs; there is no session. - POST operations that create entities return `{"id": }`. - Many integer fields (model types, status codes) map to named enums — use `GET /Definitions` to retrieve the full enum catalog at runtime. - Long-running operations (Run, Shade calculations, TABT) are asynchronous; poll the corresponding `ProcessingStatus` endpoint to track progress. - Responses may include an `X-Message` header with non-blocking warnings (e.g. duplicate project name). servers: - url: https://api.plantpredict.terabase.energy description: Production security: - bearerAuth: [] tags: - name: Definitions description: Enum and model type definitions - name: Projects description: Solar project management - name: Predictions description: Energy prediction configuration and execution - name: PowerPlant description: Power plant design (blocks, arrays, inverters, transformers) - name: TimeSeries description: Custom time series data inputs - name: Results description: Prediction results — summary, details, nodal, average energy - name: FinancialModel description: Financial model parameters and cashflow results - name: Reports description: Report generation and export - name: ShadeScene description: 3D shade scene management and calculations - name: Weather description: Weather file import, download, and management - name: Inverters description: Inverter library management - name: Modules description: PV module library and single-diode parameter generation - name: ASHRAE description: ASHRAE climate station lookup - name: System description: System version and maintenance status - name: Company description: Company settings and user management - name: Country description: Reference country data paths: /Project/{projectId}/Prediction: get: tags: - Predictions summary: List predictions for a project description: > Returns all predictions for a project. Predictions do not include power plant data; use the Power Plant operation for sub-entities. **Parameters:** - `projectId` (path, required): The project ID. operationId: listPredictions parameters: - name: projectId in: path required: true schema: type: integer responses: '200': description: Array of predictions content: application/json: schema: type: array items: $ref: '#/components/schemas/Prediction' examples: postman-predictions: value: - status: 2 start: '2005-01-01T00:00:00' end: '2005-12-31T23:00:00' startIndex: 0 endIndex: 0 yearRepeater: 1 transpositionModel: 1 perezCoefficients: 0 diffuseDirectDecompModel: 3 circumsolarTreatment: 0 diffuseDirectDecompModelExecuted: false useMeteoDni: false useMeteoPOAI: false useBacksidePOAI: false useLeapYears: false useWeatherFileAlbedoData: false useMetastability: false enableLeTID: false airMassModel: 0 soilingModel: 0 modTempModel: 0 incAngleModel: 5 directBeamShadingModel: 5 degradationModel: 0 diffuseShadingModel: 1 linearDegradationRate: 0.5 firstYearDegradation: false nonLinearDegradationRates: [] lightAndElevatedTemperatureDegradationRates: [] errorModelAcc: 2.9 errorSensAcc: 5 errorIntAnnVar: 3 errorMonAcc: 2 errorSpaVar: 2 spectralShiftModel: 2 spectralWeatherType: 0 powerPlantId: 1185523 monthlyFactors: - month: 1 monthName: Jan soilingLoss: 2 albedo: 0.2 - month: 2 monthName: Feb soilingLoss: 2 albedo: 0.2 - month: 3 monthName: Mar soilingLoss: 2 albedo: 0.2 - month: 4 monthName: Apr soilingLoss: 2 albedo: 0.2 - month: 5 monthName: May soilingLoss: 2 albedo: 0.2 - month: 6 monthName: Jun soilingLoss: 2 albedo: 0.2 - month: 7 monthName: Jul soilingLoss: 2 albedo: 0.2 - month: 8 monthName: Aug soilingLoss: 2 albedo: 0.2 - month: 9 monthName: Sep soilingLoss: 2 albedo: 0.2 - month: 10 monthName: Oct soilingLoss: 2 albedo: 0.2 - month: 11 monthName: Nov soilingLoss: 2 albedo: 0.2 - month: 12 monthName: Dec soilingLoss: 2 albedo: 0.2 horizonDetails: [] ashraeStation: RIVERPORT MUNICIPAL AP, ST, USA ashraeVersion: 2021 cool996: 32.5 max50Year: 39.4 min50Year: -30.3 minAnnualMeanDBTemp: -19.1 elevation: 184 timeZone: -5 weatherId: 230763 projectId: 187749 shadeScenePropertiesId: 4297 shadeEngineRunInfo_Id: 6806 shading3DModel: 0 tabtEngineRunInfo_Id: 802 percentComplete: 0 processingStatus: 0 processingStep: 0 processingMessage: Unknown pValues: [] isReadOnly: false pValuesString: '' nodalData: false hasTimeSeriesData: false isBatch: false batchStepVariable: [] batchQualified: true logicVersion: 12 mapBuilderCreateDCAs: 0 useMapBuilder: false scenePropertiesKey: 00000000-0000-0000-0000-000000000000 setback: 0 targetDC: 0 weatherLocked: false electricalShadingFractionalEffect: 100 numberOfModuleFractions: 0 numOfBlocks: 0 numOfWeatherDetails: 0 hasObjectShading: false numOfShadingObjects: 0 reportsId: 941620 canImportAlbedoData: false useSpectral30: false spectral30B0: -0.0967 spectral30B1: 0.0126 spectral30B2: 0 spectral30B3: 0.00223 spectral30B4: 0 spectral30B5: 0 spectral30B6: 1.086 id: 955415 name: Baseline Yield Study companyId: 1042 ownerId: 8903 createdDate: '2025-11-25T16:21:07.213' lastModified: '2025-11-25T16:22:16.553' lastModifiedById: 8903 - status: 2 start: '2005-01-01T00:00:00' end: '2005-12-31T23:00:00' lastPublishedDateToQueue: '2026-02-06T13:01:30.893' startIndex: 0 endIndex: 0 yearRepeater: 1 transpositionModel: 1 perezCoefficients: 0 diffuseDirectDecompModel: 3 circumsolarTreatment: 0 diffuseDirectDecompModelExecuted: false useMeteoDni: false useMeteoPOAI: false useBacksidePOAI: false useLeapYears: false useWeatherFileAlbedoData: false useMetastability: false enableLeTID: false airMassModel: 0 soilingModel: 0 modTempModel: 0 incAngleModel: 5 directBeamShadingModel: 5 degradationModel: 0 diffuseShadingModel: 1 linearDegradationRate: 0.5 firstYearDegradation: false nonLinearDegradationRates: [] lightAndElevatedTemperatureDegradationRates: [] errorModelAcc: 2.9 errorSensAcc: 5 errorIntAnnVar: 3 errorMonAcc: 2 errorSpaVar: 2 spectralShiftModel: 2 spectralWeatherType: 0 powerPlantId: 1187255 monthlyFactors: - month: 1 monthName: Jan soilingLoss: 2 albedo: 0.2 - month: 2 monthName: Feb soilingLoss: 2 albedo: 0.2 - month: 3 monthName: Mar soilingLoss: 2 albedo: 0.2 - month: 4 monthName: Apr soilingLoss: 2 albedo: 0.2 - month: 5 monthName: May soilingLoss: 2 albedo: 0.2 - month: 6 monthName: Jun soilingLoss: 2 albedo: 0.2 - month: 7 monthName: Jul soilingLoss: 2 albedo: 0.2 - month: 8 monthName: Aug soilingLoss: 2 albedo: 0.2 - month: 9 monthName: Sep soilingLoss: 2 albedo: 0.2 - month: 10 monthName: Oct soilingLoss: 2 albedo: 0.2 - month: 11 monthName: Nov soilingLoss: 2 albedo: 0.2 - month: 12 monthName: Dec soilingLoss: 2 albedo: 0.2 horizonDetails: - azimuth: 0 elevation: 2.3 - azimuth: 7.5 elevation: 2.3 - azimuth: 15 elevation: 2.3 - azimuth: 22.5 elevation: 2.3 - azimuth: 30 elevation: 2.3 - azimuth: 37.5 elevation: 2.3 - azimuth: 45 elevation: 1.5 - azimuth: 52.5 elevation: 1.5 - azimuth: 60 elevation: 1.5 - azimuth: 67.5 elevation: 1.5 - azimuth: 75 elevation: 1.9 - azimuth: 82.5 elevation: 1.9 - azimuth: 90 elevation: 1.9 - azimuth: 97.5 elevation: 2.3 - azimuth: 105 elevation: 2.3 - azimuth: 112.5 elevation: 1.9 - azimuth: 120 elevation: 1.9 - azimuth: 127.5 elevation: 1.9 - azimuth: 135 elevation: 1.9 - azimuth: 142.5 elevation: 1.1 - azimuth: 150 elevation: 0.8 - azimuth: 157.5 elevation: 0.4 - azimuth: 165 elevation: 0.4 - azimuth: 172.5 elevation: 0 - azimuth: 180 elevation: 0 - azimuth: 187.5 elevation: 0.4 - azimuth: 195 elevation: 0.4 - azimuth: 202.5 elevation: 0.8 - azimuth: 210 elevation: 0.4 - azimuth: 217.5 elevation: 0 - azimuth: 225 elevation: 0 - azimuth: 232.5 elevation: 0 - azimuth: 240 elevation: 0 - azimuth: 247.5 elevation: 0 - azimuth: 255 elevation: 0 - azimuth: 262.5 elevation: 0 - azimuth: 270 elevation: 0.8 - azimuth: 277.5 elevation: 1.1 - azimuth: 285 elevation: 0.8 - azimuth: 292.5 elevation: 0.8 - azimuth: 300 elevation: 0.4 - azimuth: 307.5 elevation: 1.1 - azimuth: 315 elevation: 1.1 - azimuth: 322.5 elevation: 2.3 - azimuth: 330 elevation: 2.3 - azimuth: 337.5 elevation: 2.3 - azimuth: 345 elevation: 2.3 - azimuth: 352.5 elevation: 2.3 - azimuth: 360 elevation: 2.3 ashraeStation: PRAIRIE RIDGE RGNL AP, ST, USA ashraeVersion: 2021 cool996: 37.6 max50Year: 45.4 min50Year: -28.9 minAnnualMeanDBTemp: -17.2 elevation: 229 timeZone: -6 weatherId: 139907 projectId: 187749 shading3DModel: 0 percentComplete: 100 processingStatus: 0 processingStep: 40 processingMessage: Unknown pValues: [] isReadOnly: false pValuesString: '' nodalData: false hasTimeSeriesData: false isBatch: false batchStepVariable: [] batchQualified: true logicVersion: 10 mapBuilderCreateDCAs: 0 useMapBuilder: false scenePropertiesKey: 00000000-0000-0000-0000-000000000000 setback: 0 targetDC: 0 weatherLocked: false electricalShadingFractionalEffect: 100 numberOfModuleFractions: 0 numOfBlocks: 1 numOfWeatherDetails: 8760 hasObjectShading: false numOfShadingObjects: 0 reportsId: 943796 canImportAlbedoData: false runningOnVMName: '' runCompletedDateTimeUTC: '2026-02-06T13:01:41.323' useSpectral30: false spectral30B0: -0.0967 spectral30B1: 0.0126 spectral30B2: 0 spectral30B3: 0.00223 spectral30B4: 0 spectral30B5: 0 spectral30B6: 1.086 id: 957032 name: Site B – Fixed-Tilt Baseline (v10) description: >- Cloned from prior baseline study and updated for fixed-tilt layout; created for comparative analysis. companyId: 1042 ownerId: 8903 createdDate: '2026-02-06T14:19:24.517' lastModified: '2026-02-06T14:19:24.517' lastModifiedById: 8903 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' components: schemas: Prediction: type: object required: - name properties: id: type: integer readOnly: true name: type: string description: type: - string - 'null' status: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 x-enum-varnames: - DraftPrivate - DraftShared - Analysis - Bid - Contract - Development - AsBuilt - Warranty - Archived - StringSizing description: PredictionStatusEnum projectId: type: integer powerPlantId: type: - integer - 'null' weatherId: type: - integer - 'null' start: type: string description: >- ISO-8601 datetime as returned by the PlantPredict API. May or may not include a timezone offset; treat as server-local when no offset is present. end: type: string description: >- ISO-8601 datetime as returned by the PlantPredict API. May or may not include a timezone offset; treat as server-local when no offset is present. yearRepeater: type: integer transpositionModel: type: integer enum: - 0 - 1 x-enum-varnames: - Hay - Perez description: TranspositionModelType perezCoefficients: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 x-enum-varnames: - PlantPredict - AllSitesComposite1990 - AllSitesComposite1988 - SandiaComposite1988 - USAComposite1988 - France1988 - Pheonix1988 - Elmonte1988 - Osage1988 - Albuquerque1988 - CapeCanaveral1988 - Albany1988 description: PerezCoefficientsEnum diffuseDirectDecompModel: type: integer enum: - 0 - 1 - 2 - 3 x-enum-varnames: - Erbs - Reindl - DIRINT - None description: DiffuseDirectDecompModelType circumsolarTreatment: type: integer enum: - 0 - 1 x-enum-varnames: - Diffuse - Direct description: CircumsolarTreatmentType airMassModel: type: integer enum: - 0 - 1 x-enum-varnames: - BirdHulstrom - KastenSandia description: AirMassModelType soilingModel: type: integer enum: - 0 - 1 - 2 x-enum-varnames: - MonthlyOverride - WeatherFile - None description: SoilingModelType modTempModel: type: integer enum: - 0 - 1 - 2 - 3 x-enum-varnames: - HeatBalance - Sandia - NOCT - DCFieldDefined description: ModuleTemperatureModelType incAngleModel: type: integer enum: - 2 - 3 - 4 - 5 - 6 x-enum-varnames: - Sandia - ASHRAE - None - TabularIAM - PhysicalIAM description: IncidenceAngleModelType directBeamShadingModel: type: integer enum: - 0 - 1 - 2 - 3 - 5 - 6 x-enum-varnames: - Linear - None - V2DimensionRetired - FractionalElectricalShading - ModuleFileDefinedShading - StepFractionalElectricalShading description: DirectBeamShadingModel degradationModel: type: integer enum: - 0 - 1 - 2 - 3 - 4 x-enum-varnames: - None - SteppedAC - LinearAC - LinearDC - NonLinearDC description: DegradationModel diffuseShadingModel: type: integer enum: - 0 - 1 x-enum-varnames: - None - SchaarPanchula description: DiffuseShadingModel spectralShiftModel: type: integer enum: - 0 - 1 - 2 - 3 x-enum-varnames: - None - V1ParamPwatOrSandia - V2ParamPwatAndAM - MonthlyOverride description: SpectralShiftModel linearDegradationRate: type: number firstYearDegradation: type: boolean errorModelAcc: type: number errorSensAcc: type: number errorIntAnnVar: type: number errorMonAcc: type: number errorSpaVar: type: number useMeteoDni: type: boolean useMeteoPOAI: type: boolean useBacksidePOAI: type: boolean useLeapYears: type: boolean useWeatherFileAlbedoData: type: boolean useMetastability: type: boolean enableLeTID: type: boolean max50Year: type: number min50Year: type: number cool996: type: number minAnnualMeanDBTemp: type: - number - 'null' elevation: type: - number - 'null' timeZone: type: - number - 'null' ashraeStation: type: string ashraeWMO: type: string ashraeDistance: type: number ashraeVersion: type: integer enum: - 0 - 1 x-enum-varnames: - Version2013 - Version2021 description: AshraeVersionEnum logicVersion: type: integer enum: - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 x-enum-varnames: - Version3 - Version4 - Version5 - Version6 - Version7 - Version8 - Version9 - Version10 - Version11 - Version12 - Version13Beta description: PredictionVersionEnum pValues: type: array items: type: object horizonDetails: type: array items: type: object nonLinearDegradationRates: type: array items: type: object monthlyFactors: type: array items: $ref: '#/components/schemas/MonthlyFactor' MonthlyFactor: type: object properties: id: type: integer month: type: integer minimum: 1 maximum: 12 monthName: type: string soilingLoss: type: number albedo: type: number spectralShift: type: - number - 'null' responses: Unauthorized: description: >- Missing or invalid bearer token. The response body is empty and no `Content-Type` header is set; the 401 status code is the only signal. Fetch a fresh token (see the **Authentication** section of the API description) and retry. NotFound: description: >- The referenced resource does not exist or is not accessible to the caller. content: text/plain: schema: type: string example: Project not found. ServerError: description: | Unexpected server-side error. The body is usually a plain-text message but its structure is not guaranteed — treat it as opaque diagnostic text. Common causes: database constraint violation, downstream service timeout, internal exception. Retry-safe for idempotent requests; for non-idempotent ones, verify state before retrying. content: text/plain: schema: type: string example: An error has occurred. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Pass `Authorization: Bearer ` on every request. See the **Authentication** section of the API description for how to fetch a token. ````