> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/reports.md).

# Reports

Business numbers, as the Reports pages show them.

A metric is one number from the Reports pages (revenue, MRR, money owed, crew hours, sales, customers) for a period, worked out the same way. Margin numbers are not available to tokens.

Fields: [The metric object](https://docs.shortcutco.com/developers/reference/objects/metric).

## Get the cash outlook for 30, 60 and 90 days

> Money expected in over the next 30, 60 and 90 days from what Shortcut stores, each part apart: open invoices due in each window (what is left to pay, and the part owed by autopay customers), open invoices already past due or with no due date (when they come in is not known), and visits booked in each window at their price (the Reports metric \`revenue.scheduled\`), which are billed once done. The last 90 days' cancellation and autopay failure rates (Reports' \`ops.cancel\_rate\` and \`ops.autopay\_failure\_rate\`) come off booked work and the autopay part, each on its own line. Nothing is added up across parts and no customer's lateness is applied; \`leftOut\` says what is not included (the bank balance, payroll and bills, which live in the books).\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`balance\_evidence\_limit\`]\(<https://docs.shortcutco.com/developers/concepts/errors#balance\\_evidence\\_limit>), \[\`balance\_evidence\_unavailable\`]\(<https://docs.shortcutco.com/developers/concepts/errors#balance\\_evidence\\_unavailable>), \[\`metric\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#metric\\_not\\_available>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Reports","description":"A metric is one number from the Reports pages (revenue, MRR, money owed, crew hours, sales, customers) for a period, worked out the same way. Margin numbers are not available to tokens.\n\nFields: [The metric object](https://docs.shortcutco.com/developers/reference/objects/metric)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["reports:read","invoices:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/reports/cash-outlook":{"get":{"operationId":"reports.cash_outlook.get","tags":["Reports"],"summary":"Get the cash outlook for 30, 60 and 90 days","description":"Money expected in over the next 30, 60 and 90 days from what Shortcut stores, each part apart: open invoices due in each window (what is left to pay, and the part owed by autopay customers), open invoices already past due or with no due date (when they come in is not known), and visits booked in each window at their price (the Reports metric `revenue.scheduled`), which are billed once done. The last 90 days' cancellation and autopay failure rates (Reports' `ops.cancel_rate` and `ops.autopay_failure_rate`) come off booked work and the autopay part, each on its own line. Nothing is added up across parts and no customer's lateness is applied; `leftOut` says what is not included (the bank balance, payroll and bills, which live in the books).\n\n**Errors specific to this endpoint:** [`balance_evidence_limit`](https://docs.shortcutco.com/developers/concepts/errors#balance_evidence_limit), [`balance_evidence_unavailable`](https://docs.shortcutco.com/developers/concepts/errors#balance_evidence_unavailable), [`metric_not_available`](https://docs.shortcutco.com/developers/concepts/errors#metric_not_available), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"asOf":{"type":"string","description":"Today, `YYYY-MM-DD`, in the company's time zone."},"pastDue":{"type":"number","description":"Open invoices already past their due date, what is left to pay, US dollars. When it comes in is not known."},"pastDueCount":{"type":"integer"},"noDueDate":{"type":"number","description":"Open invoices with no due date, what is left to pay."},"noDueDateCount":{"type":"integer"},"windows":{"type":"array","items":{"type":"object","properties":{"days":{"type":"integer"},"through":{"type":"string","description":"The window's last day, `YYYY-MM-DD`, in the company's time zone."},"invoicesDue":{"type":"number","description":"Open invoices due from today through `through`, what is left to pay on them, US dollars."},"invoicesDueCount":{"type":"integer"},"invoicesDueOnAutopay":{"type":"number","description":"The part of `invoicesDue` owed by customers with autopay on."},"bookedWork":{"type":["number","null"],"description":"Visits booked from today through `through` at their price (`revenue.scheduled`): billed once done, so paid later. Null when Reports can't measure it."},"bookedVisits":{"anyOf":[{"type":"integer"},{"type":"null"}]},"bookedWorkLessCancellations":{"type":["number","null"],"description":"`bookedWork` less the share of visits cancelled over the last 90 days (`rates.cancelRate`). Null when either is unknown."},"invoicesDueOnAutopayLessFailures":{"type":["number","null"],"description":"`invoicesDueOnAutopay` less the share of autopay charges that failed over the last 90 days (`rates.autopayFailureRate`). Null when that rate is unknown."}},"required":["days","through","invoicesDue","invoicesDueCount","invoicesDueOnAutopay","bookedWork","bookedVisits","bookedWorkLessCancellations","invoicesDueOnAutopayLessFailures"],"additionalProperties":false}},"rates":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"cancelRate":{"type":["number","null"],"description":"Scheduled visits cancelled, as a share from 0 to 1 (the Reports metric `ops.cancel_rate`). Null when Reports has too little history."},"autopayFailureRate":{"type":["number","null"],"description":"Autopay charges that failed, as a share from 0 to 1 (`ops.autopay_failure_rate`). Null when Reports has too little history."}},"required":["from","to","cancelRate","autopayFailureRate"],"additionalProperties":false,"description":"The last 90 days' rates, read from Reports; history, not a promise."},"leftOut":{"type":"array","items":{"type":"string"},"description":"What the outlook does not include, in plain words."}},"required":["asOf","pastDue","pastDueCount","noDueDate","noDueDateCount","windows","rates","leftOut"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a business number

> One number from the Reports pages (revenue, MRR, money owed, crew hours, sales, customers), worked out exactly as the Reports pages do, for a period, optionally grouped and compared. Margin numbers answer \`not\_allowed\`. \`GET /v1/reports/metrics\` lists the metrics.\
> \
> Returns \[the metric object]\(<https://docs.shortcutco.com/developers/reference/objects/metric).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`metric\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#metric\\_not\\_available>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Reports","description":"A metric is one number from the Reports pages (revenue, MRR, money owed, crew hours, sales, customers) for a period, worked out the same way. Margin numbers are not available to tokens.\n\nFields: [The metric object](https://docs.shortcutco.com/developers/reference/objects/metric)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["reports:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Metric":{"type":"object","properties":{"object":{"type":"string","const":"metric","description":"Always `metric`."},"metric":{"type":"string","description":"The metric's id."},"name":{"type":"string","description":"Its name on the Reports pages."},"unit":{"type":"string","enum":["money","count","percent","days","minutes","hours"],"description":"Money is US dollars; percent is a share from 0 to 1."},"definition":{"type":"string","description":"What it counts, in a sentence."},"status":{"type":"string","enum":["ok","not_enough","not_ready","no_data","not_allowed"],"description":"`ok`: `value` is the number. `not_enough` / `not_ready`: too little data yet. `no_data`: nothing in the window. `not_allowed`: margin numbers, which tokens cannot read."},"value":{"type":["number","null"],"description":"The number, when `status` is `ok`. Quote it as given; never add up or average metrics yourself."},"period":{"$ref":"#/components/schemas/MetricPeriod"},"previous":{"anyOf":[{"$ref":"#/components/schemas/MetricComparison"},{"type":"null"}],"description":"The comparison, when `compare` was asked."},"usual":{"type":"object","properties":{"status":{"type":"string","enum":["ok","insufficient_data"]},"lower":{"type":["number","null"]},"upper":{"type":["number","null"]},"sampleCount":{"type":"integer","minimum":0,"maximum":12},"required":{"type":"number","const":12},"method":{"type":"string","const":"linear_p10_p90"},"windows":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"value":{"type":["number","null"]}},"required":["from","to","value"],"additionalProperties":false},"minItems":12,"maxItems":12}},"required":["status","lower","upper","sampleCount","required","method","windows"],"additionalProperties":false},"components":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["available","partial","unavailable"]},"value":{"type":["number","null"]},"unit":{"type":"string","enum":["money","count","percent","days","minutes","hours"]},"count":{"type":"integer","minimum":0},"notes":{"type":"array","items":{"type":"string"}}},"required":["key","label","status","value","unit","count","notes"],"additionalProperties":false}},"completeness":{"type":"object","properties":{"complete":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}}},"required":["complete","reasons"],"additionalProperties":false},"rows":{"type":"array","items":{"$ref":"#/components/schemas/MetricRow"},"description":"Grouped rows, when `groupBy` was asked; empty otherwise."},"truncated":{"type":"boolean","description":"Whether more than 50 rows existed."},"coverage":{"$ref":"#/components/schemas/MetricCoverage"},"asOf":{"type":"string","format":"date-time","description":"When it was worked out."},"reportUrl":{"type":"string","format":"uri","description":"The Reports page that shows the same number."}},"required":["object","metric","name","unit","definition","status","value","period","previous","rows","truncated","coverage","asOf","reportUrl"],"additionalProperties":false,"description":"A business number from the Reports pages."},"MetricPeriod":{"type":"object","properties":{"from":{"type":"string","description":"The first day covered, `YYYY-MM-DD` in the workspace's timezone."},"to":{"type":"string","description":"The last day covered, included."},"label":{"type":"string","description":"How the Reports page labels the window."}},"required":["from","to","label"],"additionalProperties":false,"description":"The window a metric covers."},"MetricComparison":{"type":"object","properties":{"value":{"type":["number","null"],"description":"The comparison window's number."},"label":{"type":"string","description":"Its label."}},"required":["value","label"],"additionalProperties":false,"description":"The same metric for the comparison window."},"MetricRow":{"type":"object","properties":{"key":{"type":"string","description":"The row's id: a crew, service, customer, or other grouping key."},"label":{"type":"string","description":"The row's name."},"value":{"type":["number","null"],"description":"The row's number."},"count":{"type":"integer","description":"How many records sit behind it."},"notes":{"type":"array","items":{"type":"string"},"description":"Native cohort or provenance cautions for this row."}},"required":["key","label","value","count"],"additionalProperties":false,"description":"One row of a grouped metric."},"MetricCoverage":{"type":"object","properties":{"included":{"type":"integer","description":"Records counted."},"total":{"type":"integer","description":"Records that could have been."},"unit":{"type":"string","description":"What a record is, e.g. `invoices`."}},"required":["included","total","unit"],"additionalProperties":false,"description":"How much of the data the number covers. Say so when `included` is less than `total`."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/reports/metric":{"get":{"operationId":"reports.metric.get","tags":["Reports"],"summary":"Get a business number","description":"One number from the Reports pages (revenue, MRR, money owed, crew hours, sales, customers), worked out exactly as the Reports pages do, for a period, optionally grouped and compared. Margin numbers answer `not_allowed`. `GET /v1/reports/metrics` lists the metrics.\n\nReturns [the metric object](https://docs.shortcutco.com/developers/reference/objects/metric).\n\n**Errors specific to this endpoint:** [`metric_not_available`](https://docs.shortcutco.com/developers/concepts/errors#metric_not_available). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"metric","in":"query","required":true,"description":"The metric, e.g. `revenue.mrr`. `GET /v1/reports/metrics` lists every metric with the periods and groupings it takes.","schema":{"type":"string","enum":["revenue.completed","revenue.invoiced","revenue.collected","revenue.mrr","revenue.scheduled","revenue.adjustments","revenue.sales_tax","revenue.prepay_unearned","revenue.backlog","ar.outstanding","sales.close_rate","ops.effective_hourly_rate","ops.on_site_share","ops.priced_vs_actual","ops.margin","ops.net_profit","ops.material_variance","capacity.booked","ar.days_to_pay","ar.median_days_to_pay","ar.paid_late_count","payments.method_share","sales.open_quotes","ar.overdue_with_work_done","sales.upsell_gaps","sales.lead_response_time","ops.reschedule_rate","ops.rain_days","ops.skip_reasons","ops.program_progress","ops.price_per_thousand_sqft","ops.cost_per_thousand_sqft","customers.cohort","customers.retained","customers.new","customers.at_risk","customers.churn_after_price_change","leads.new","sales.estimate_lead_time","inbox.first_response_time","sales.losses","customers.churned","ops.minutes_per_thousand_sqft","ops.labor_hours","ops.working_days","ops.autopay_failure_rate","ops.cancel_rate"]}},{"name":"period","in":"query","required":true,"description":"The window: the current week, month, quarter, or year to date; `now`; the next 7 or 14 days; or `custom` with `from` and `to`.","schema":{"type":"string","enum":["custom","month","next_14_days","next_7_days","now","quarter","rest_of_month","week","ytd"]}},{"name":"from","in":"query","required":false,"description":"For `custom`: the first day, `YYYY-MM-DD`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"For `custom`: the last day, included.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"groupBy","in":"query","required":false,"description":"Split the number into rows (at most 50), e.g. by crew or service.","schema":{"type":"string","enum":["adjustment_kind","aging_bucket","cadence","churn_reason","crew","crew_day","crew_weekday","customer","day","decline_reason","invoicing_mode","lead_source","lot_size_band","month","payment_method","product","property","risk_reason","salesperson","service","skip_reason","snow_depth","source","state","week","weekday"]}},{"name":"compare","in":"query","required":false,"description":"prior/year_ago: one window. usual: middle80% of12 like periods, with missing history explicit.","schema":{"type":"string","enum":["prior","year_ago","usual"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Metric"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List business numbers

> Every metric \`GET /v1/reports/metric\` answers, with the periods and groupings each takes.

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Reports","description":"A metric is one number from the Reports pages (revenue, MRR, money owed, crew hours, sales, customers) for a period, worked out the same way. Margin numbers are not available to tokens.\n\nFields: [The metric object](https://docs.shortcutco.com/developers/reference/objects/metric)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["reports:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"MetricDefinition":{"type":"object","properties":{"id":{"type":"string","description":"The metric's id."},"name":{"type":"string","description":"Its name."},"unit":{"type":"string","enum":["money","count","percent","days","minutes","hours"],"description":"Its unit."},"periods":{"type":"array","items":{"type":"string"},"description":"The `period` values it takes."},"groupings":{"type":"array","items":{"type":"string"},"description":"The `groupBy` values it takes."},"marginsOnly":{"type":"boolean","description":"Whether it needs the margins permission, which tokens never hold (it answers `not_allowed`)."}},"required":["id","name","unit","periods","groupings","marginsOnly"],"additionalProperties":false,"description":"A metric the catalog answers."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/reports/metrics":{"get":{"operationId":"reports.metrics.list","tags":["Reports"],"summary":"List business numbers","description":"Every metric `GET /v1/reports/metric` answers, with the periods and groupings each takes.","parameters":[],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MetricDefinition"}},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read observed sold prices

> Observed low, median and high per-service prices from complete finished visits in the property's size band. Current cadence and pricing bases stay separate; source gaps and small samples are explicit.\
> \
> Returns \[the price range object]\(<https://docs.shortcutco.com/developers/reference/objects/price-range).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`automation\_draft\_invalid\`]\(<https://docs.shortcutco.com/developers/concepts/errors#automation\\_draft\\_invalid>), \[\`clip\_write\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#clip\\_write\\_not\\_allowed>), \[\`invalid\_price\_range\`]\(<https://docs.shortcutco.com/developers/concepts/errors#invalid\\_price\\_range>), \[\`price\_range\_limit\`]\(<https://docs.shortcutco.com/developers/concepts/errors#price\\_range\\_limit>), \[\`service\_not\_found\`]\(<https://docs.shortcutco.com/developers/concepts/errors#service\\_not\\_found>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Reports","description":"A metric is one number from the Reports pages (revenue, MRR, money owed, crew hours, sales, customers) for a period, worked out the same way. Margin numbers are not available to tokens.\n\nFields: [The metric object](https://docs.shortcutco.com/developers/reference/objects/metric)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["reports:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"PriceRange":{"type":"object","properties":{"object":{"type":"string","const":"price_range"},"service":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"asOf":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["available","no_data"]},"window":{"type":"object","properties":{"from":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"to":{"type":"string","format":"date-time"},"basis":{"type":"string","enum":["requested_completion_window","all_retained_completed_history"]}},"required":["from","to","basis"],"additionalProperties":false},"sizeBand":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false},"cohorts":{"type":"array","items":{"type":"object","properties":{"cadence":{"type":"object","properties":{"kind":{"type":"string","enum":["one_off","recurring","on_demand","unknown"]},"frequency":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"period":{"anyOf":[{"type":"string","enum":["per_day","per_week","per_month","per_year"]},{"type":"null"}]}},"required":["kind","frequency","period"],"additionalProperties":false},"pricingBases":{"type":"array","items":{"type":"string"}},"unit":{"type":"string","const":"USD_per_completed_service_visit"},"low":{"type":"number"},"middle":{"type":"number"},"high":{"type":"number"},"sampleCount":{"type":"integer","exclusiveMinimum":0},"history":{"type":"string","enum":["small_sample","observed_history"]}},"required":["cadence","pricingBases","unit","low","middle","high","sampleCount","history"],"additionalProperties":false}},"coverage":{"type":"object","properties":{"included":{"type":"integer"},"total":{"type":"integer"},"excluded":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"count":{"type":"integer"}},"required":["reason","count"],"additionalProperties":false}}},"required":["included","total","excluded"],"additionalProperties":false},"notes":{"type":"array","items":{"type":"string"}}},"required":["object","service","asOf","status","window","sizeBand","cohorts","coverage","notes"],"additionalProperties":false,"description":"Observed sold-price ranges per completed native service visit, with current size/cadence classifications and explicit evidence coverage."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/reports/price-range":{"get":{"operationId":"reports.price_range.get","tags":["Reports"],"summary":"Read observed sold prices","description":"Observed low, median and high per-service prices from complete finished visits in the property's size band. Current cadence and pricing bases stay separate; source gaps and small samples are explicit.\n\nReturns [the price range object](https://docs.shortcutco.com/developers/reference/objects/price-range).\n\n**Errors specific to this endpoint:** [`automation_draft_invalid`](https://docs.shortcutco.com/developers/concepts/errors#automation_draft_invalid), [`clip_write_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#clip_write_not_allowed), [`invalid_price_range`](https://docs.shortcutco.com/developers/concepts/errors#invalid_price_range), [`price_range_limit`](https://docs.shortcutco.com/developers/concepts/errors#price_range_limit), [`service_not_found`](https://docs.shortcutco.com/developers/concepts/errors#service_not_found). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"serviceId","in":"query","required":true,"description":"The native service ID.","schema":{"type":"string","format":"uuid"}},{"name":"squareFeet","in":"query","required":true,"description":"Property square feet; uses the existing lot-size band.","schema":{"type":"number","exclusiveMinimum":0}},{"name":"cadence","in":"query","required":false,"description":"Optional exact current Job cadence; recurring also requires frequency and cadencePeriod.","schema":{"type":"string","enum":["one_off","recurring","on_demand","unknown"]}},{"name":"frequency","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0}},{"name":"cadencePeriod","in":"query","required":false,"schema":{"type":"string","enum":["per_day","per_week","per_month","per_year"]}},{"name":"from","in":"query","required":false,"description":"Optional first company-local completion day; provide to as well. Default: all retained finished history.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Optional last completion day, included; future work never counts.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PriceRange"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```
