openapi: 3.0.0 info: title: Reports API description: Access & Create Usage Reports version: 1.0.0 servers: - url: https://api.planet.com/reports/v1/ description: API Server components: schemas: Report: type: object properties: report_id: type: string contents: description: Link to one or more report files. type: array items: type: string format: url org_id: type: integer plan_id: type: integer data_date_start: type: string format: date data_date_end: type: string format: date report_type: $ref: '#/components/schemas/ReportType' num_rows: type: integer cadence: $ref: '#/components/schemas/Cadence' has_footprint: description: If true, report files contain geometry footprints. type: boolean _links: $ref: '#/components/schemas/ReportLinks' PVReport: type: object properties: report_id: type: string contents: description: Link to one or more PV report files. type: array items: type: string format: url org_id: type: integer plan_id: type: integer line_item_id: type: integer data_date_start: type: string format: date data_date_end: type: string format: date report_type: $ref: '#/components/schemas/ReportType' num_rows: type: integer cadence: $ref: '#/components/schemas/Cadence' has_footprint: description: If true, PV report files contain geometry footprints. type: boolean _links: $ref: '#/components/schemas/ReportLinks' SubOrgReport: allOf: - $ref: '#/components/schemas/SubOrgReportRequest' - type: object properties: report_id: type: string format: uuid status: type: string enum: - in_progress - failed - completed parent: description: parent organisation id type: integer requesting_user_id: type: integer contents: description: Link to one or more report files. type: array items: type: string format: url SubOrgReportRequest: type: object properties: report_type: $ref: '#/components/schemas/ReportType' cadence: $ref: '#/components/schemas/Cadence' toi: $ref: '#/components/schemas/TOI' suborgs: type: object properties: include: type: string enum: - all - none - selected ids: type: array items: type: integer Cadence: type: string enum: - daily - monthly Type: type: string enum: - scenes - basemaps Plan: type: string enum: - asset_area_under_management_sqkm_v1_0 - asset_area_under_management_sqkm_v2_0 - asset_preferred_sqkm_v1_0 - asset_premium_sqkm_v1_0 - asset_starter_sqkm_v1_0 - on_demand_large_areas_v1 - tasking_credits_v1_0 QuotaStyle: type: string description: Plan definition ID used to filter download reports by quota style enum: - asset_area_under_management_sqkm_v1_0 - asset_area_under_management_sqkm_v2_0 - asset_preferred_sqkm_v1_0 - asset_premium_sqkm_v1_0 - asset_starter_sqkm_v1_0 - on_demand_large_areas_v1 - tasking_credits_v1_0 ReportType: type: string enum: - detailed - summary PvReportType: type: string enum: - pv_detailed - billableaoi_detailed ReportLinks: type: object properties: self: type: string ListPage: type: object properties: reports: type: array items: $ref: '#/components/schemas/Report' _links: type: object properties: next: type: string format: url FootprintsReportRequest: type: object properties: aoi: $ref: '#/components/schemas/Geometry' toi: $ref: '#/components/schemas/TOI' org_id: type: integer plan_id: type: integer TOI: type: object description: >- Time of interest, the time window cannot be greater than 90 days, start date and end date included properties: start_date: type: string format: date end_date: type: string format: date FootprintsReportResponse: allOf: - $ref: '#/components/schemas/FootprintsReportRequest' - type: object properties: status_link: type: string format: url location: type: string format: url FootprintsReport: type: object properties: id: type: string report_date: type: string format: date report_type: $ref: '#/components/schemas/ReportType' usage_bucket: type: string org: type: integer package: type: integer plan: type: integer content_link: type: string FootprintsReportsListResponse: type: object properties: reports: type: array items: $ref: '#/components/schemas/FootprintsReport' Geometry: type: object description: Area of interest - GeoJSon geometry externalDocs: url: http://geojson.org/geojson-spec.html#geometry-objects oneOf: - $ref: '#/components/schemas/Polygon' - $ref: '#/components/schemas/MultiPolygon' Polygon: type: object description: GeoJSon geometry externalDocs: url: http://geojson.org/geojson-spec.html#id4 properties: type: type: string enum: - Polygon coordinates: type: array items: type: array items: $ref: '#/components/schemas/Point2D' additionalProperties: false MultiPolygon: type: object description: GeoJSon geometry externalDocs: url: http://geojson.org/geojson-spec.html#id6 properties: type: type: string enum: - MultiPolygon coordinates: type: array items: type: array items: type: array items: $ref: '#/components/schemas/Point2D' additionalProperties: false Point2D: type: array maxItems: 2 minItems: 2 items: type: number Error: type: object properties: message: description: A descriptive error message. type: string additionalProperties: false Errors: description: A list of Errors type: array items: $ref: '#/components/schemas/Error' APIError: description: >- An APIError communicates both general and field-specific errors. General errors include issues with core API usage as well as conflicts that involve more than one field. Field-specific errors correspond to an individual query parameter or request body attribute. Errors referencing nested fields will be dot-delimited (e.g. user.groups.0.name). type: object properties: field: additionalProperties: $ref: '#/components/schemas/Errors' type: object general: $ref: '#/components/schemas/Errors' additionalProperties: false required: - general - field Offset: type: integer minimum: 0 paths: /: get: tags: - Download Reports description: List reports, using and filtering logic based on parameters operationId: listReports summary: List Download Reports parameters: - name: org_id in: query description: ID of org to query, defaults to token claims schema: type: integer - name: plan_id in: query description: Include reports generated for the given Plan ID schema: type: integer - name: quota_style in: query description: Filter reports by plan definition ID (quota style) schema: $ref: '#/components/schemas/QuotaStyle' - name: bucket_prn in: query description: Filter reports by usage bucket PRN schema: type: string example: prn:usage-api:bucket:7a02db3e-1d68-47bf-8219-97cfb6e0b3c8 - name: report_type in: query description: Report type schema: $ref: '#/components/schemas/ReportType' - name: cadence in: query description: Report cadence schema: type: string enum: - daily - monthly - name: start in: query description: Include reports on or after this date schema: type: string format: date - name: end in: query description: Include reports on or before this date schema: type: string format: date - name: page_size in: query description: Number of records to return per page, defaults to 50. schema: type: integer - name: after in: query description: Paging navigation - specifies ID of report to start listing from. schema: type: string - name: offset in: query description: Number of results to skip in a query schema: $ref: '#/components/schemas/Offset' responses: '200': description: List of Reports matching filter criteria content: application/json: schema: $ref: '#/components/schemas/ListPage' /{id}: get: tags: - Download Reports description: Get a report by ID operationId: getReport summary: Get a Download Report parameters: - name: id in: path description: ID of report to get required: true schema: type: string responses: '200': $ref: '#/components/schemas/Report' /{id}/content/{part}: get: tags: - Download Reports description: Download a report operationId: getReportContent summary: Get a Download Report's content parameters: - name: id description: ID of report to get in: path required: true schema: type: string - name: part description: Part of report to get in: path required: true schema: type: integer responses: '200': description: Report contents content: text/csv: schema: type: string /pv/: get: tags: - PV Reports description: List PV reports, using filtering logic based on parameters operationId: listPVReports summary: List PV Reports parameters: - name: org_id in: query description: ID of org to query, defaults to token claims schema: type: integer - name: plan_id in: query description: Include PV reports generated for the given Contract ID schema: type: integer - name: line_item_id in: query description: Include PV reports generated for the given Line Item ID schema: type: integer - name: report_type in: query description: PV report type schema: $ref: '#/components/schemas/PvReportType' - name: cadence in: query description: >- PV report cadence _Please note that no monthly reports are created for the pv_detailed report_type. A list of monthly pv_detailed reports will always be empty_ schema: $ref: '#/components/schemas/Cadence' - name: start in: query description: Include PV reports on or after this date schema: type: string format: date - name: end in: query description: Include PV reports on or before this date schema: type: string format: date - name: page_size in: query description: Number of records to return per page, defaults to 50 for PV reports. schema: type: integer - name: after in: query description: Paging navigation - specifies ID of PV report to start listing from. schema: type: string - name: offset in: query description: Number of results to skip in a query schema: $ref: '#/components/schemas/Offset' responses: '200': description: List of PV Reports matching filter criteria content: application/json: schema: $ref: '#/components/schemas/ListPage' /pv/{reportId}: get: tags: - PV Reports description: Get a PV report by ID operationId: getPVReport summary: Get a PV Report parameters: - name: reportId in: path description: ID of the PV report to get required: true schema: type: string responses: '200': $ref: '#/components/schemas/PVReport' /downloads/suborgs: post: tags: - Downloads Reports (Sub Orgs) description: >- Request to generate a download usage report of "all" or "selected" Suborganizations of the Organization the requesting user belongs to. operationId: createSuborgReport summary: Create a SubOrg Download Report requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubOrgReportRequest' responses: '201': $ref: '#/components/schemas/SubOrgReport' /downloads/suborgs/{id}: get: tags: - Downloads Reports (Sub Orgs) description: Get a sub org report by ID operationId: getSubOrgReport summary: SubOrg Download Report parameters: - name: id in: path description: ID of sub org report required: true schema: type: string format: uuid responses: '200': $ref: '#/components/schemas/SubOrgReport' /downloads/suborgs/{id}/content/{part}: get: tags: - Downloads Reports (Sub Orgs) description: Download a report operationId: getSubOrgDownloadReportContent summary: SubOrg Download Report's Content parameters: - name: id description: ID of suborg report to get in: path required: true schema: type: string format: uuid - name: part description: Part of report to get in: path required: true schema: type: integer responses: '200': description: SubOrg Report contents as csv content: text/csv: schema: type: string /plans/{planID}/tiles/usage: get: tags: - Tiles Streaming Reports description: Download tiles usage report operationId: getTilesUsageReport summary: Get Tiles Usage Report parameters: - name: planID in: path description: >- ID of plan to request the report (you can find this ID in the Accounts Page) required: true schema: type: integer - name: start in: query description: The report will include results after this date (YYYY-MM-DD) required: true schema: type: string format: date - name: end in: query description: The report will include results before this date (YYYY-MM-DD) required: true schema: type: string format: date - name: include_user in: query description: If true, the report will contains the user required: true schema: type: boolean - name: interval in: query description: Report cadence, can be daily or monthly required: true schema: $ref: '#/components/schemas/Cadence' - name: type in: query description: Optional filter by tile type, can be scenes or basemaps required: false schema: $ref: '#/components/schemas/Type' - name: include_subject in: query description: >- If true, the report will include the subject for every streaming event required: false schema: type: boolean responses: '200': description: Subscriptions report content: text/csv: schema: type: string '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/APIError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' /tasking/{contractId}/usage: get: tags: - Tasking Reports description: > Download a usage report for a tasking contract. By default returns a tasking usage report. Pass `?type=dedicated-capacity` to get a dedicated capacity report instead. operationId: getTaskingUsageReport summary: Get Tasking Usage Report parameters: - name: contractId description: tasking contract ID (pl-number) in: path required: true schema: type: string - name: type in: query required: false description: > Report variant. Omit for a standard tasking usage report. Use `dedicated-capacity` for a dedicated capacity report. schema: type: string enum: - dedicated-capacity - name: start_date in: query required: false description: Start of the reporting window. Accepts YYYY-MM-DD or RFC3339. schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - name: end_date in: query required: false description: End of the reporting window. Accepts YYYY-MM-DD or RFC3339. schema: type: string format: date-time example: '2025-03-31T23:59:59Z' - name: limit in: query required: false description: Maximum number of rows to return. Must be a positive integer. schema: type: integer example: 100 - name: exclude in: query required: false description: >- Column headers to be excluded from the CSV report. Include the query param for each column schema: type: array items: type: string style: form explode: true responses: '200': description: | Report as a CSV file attachment. headers: Content-Disposition: description: attachment; filename=".csv" schema: type: string content: text/csv: schema: type: string '204': description: No results found for the given parameters. '400': description: >- Invalid `limit` (non-integer) or unparseable `start_date`/`end_date`. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Caller does not have access to the PL number's owning org. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- PL number not found in Contract Manager, or endpoint disabled by feature flag. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Upstream error from Oden, or orders field was redacted. content: application/json: schema: $ref: '#/components/schemas/Error' /footprints/{planId}: get: tags: - Footprints Reports description: >- Returns the download footprints geometry reports generated for the given Plan ID operationId: getFootprintsReports summary: Get Footprints Usage Reports parameters: - name: planId in: path description: ID of the plan required: true schema: type: integer responses: '200': description: List of footprints reports content: application/json: schema: $ref: '#/components/schemas/FootprintsReportsListResponse' /footprints/{planId}/{reportId}: get: tags: - Footprints Reports description: >- Returns the download footprints report generated for the given Plan ID and Report Id operationId: getFootprintsReport summary: Get a single Footprints Usage Report parameters: - name: planId in: path description: ID of the plan required: true schema: type: integer - name: reportId in: path description: ID of the requested report required: true schema: type: string format: uuid responses: '200': description: Footprint geometry generated content: application/json: schema: $ref: '#/components/schemas/Geometry' /footprints/product/{productId}: get: tags: - Footprints Reports description: >- Returns the footprints geometry reports for the given Product Access ID. Reports are queried by Product Access ID, which is resolved to the usage bucket it points at. Footprints are recorded per usage bucket, so Product Accesses that share a bucket see the same reports, including reports dated before a given Product Access was created. operationId: getFootprintsReportsByProduct summary: Get Footprints Usage Reports by Product Access ID parameters: - name: productId in: path description: ID of the product access required: true schema: type: integer responses: '200': description: List of footprints reports content: application/json: schema: $ref: '#/components/schemas/FootprintsReportsListResponse' /footprints/product/{productId}/{reportId}: get: tags: - Footprints Reports description: >- Returns the footprints report with the given Report Id for the given Product Access ID. Reports are queried by Product Access ID, and the report must belong to the usage bucket that Product Access points at; otherwise the request fails as if the report did not exist. operationId: getFootprintsReportByProduct summary: Get a single Footprints Usage Report by Product Access ID parameters: - name: productId in: path description: ID of the product access required: true schema: type: integer - name: reportId in: path description: ID of the requested report required: true schema: type: string format: uuid responses: '200': description: Footprint geometry generated content: application/json: schema: $ref: '#/components/schemas/Geometry'