---
title: "Get City Metrics Monthly"
method: GET
path: "/cities/{geo_id}/metrics/monthly"
tags: ["Cities"]
---

# Get City Metrics Monthly

`GET /cities/{geo_id}/metrics/monthly`

Returns monthly city metrics.

## Path parameters

- `geo_id` string, required — Filter by the specified city ID.

## Query parameters

- `metric_from` string, date, required — Start date for metrics (inclusive)
- `metric_to` string, date, required — End date for metrics (inclusive)
- `property_type` string, required — Filter by property type
- `tag` string, required — Filter by tag
- `cursor` string, nullable — Cursor for pagination
- `size` integer

## Response `200`

Monthly metrics for the city

- PaginatedCitiesMetricsMonthly — Schema for cursor-paginated city monthly metrics response.
  - `items` CitiesMetricsMonthlyRead[], required — The list of items returned in the response following given criteria.
    - `geo_id` string, required — Unique identifier for the entity
    - `tag` string, nullable, required — Specific tag or category for the metrics
    - `permit_count` integer, nullable — Total number of permits issued
    - `contractor_count` integer, nullable — Total number of unique contractors
    - `avg_construction_duration` integer, nullable — Average duration of construction projects in days
    - `avg_approval_duration` integer, nullable — Average duration of permit approval process in days
    - `total_job_value` integer, nullable — Total value of all jobs/permits in cents (integer value representing dollars × 100)
    - `avg_inspection_pass_rate` integer, nullable — Average pass rate for inspections (percentage in integer format 0-100)
    - `date` string, date, required — The month for which the metrics are calculated
    - `property_type` string, nullable — Type of property (e.g., residential, commercial)
  - `size` integer, required — The number of items returned in the response.
  - `next_cursor` string, nullable, required — The cursor for retrieving the next page of results.
  - `total_count` TotalCount — Capped result count with Elasticsearch-style {value, relation} shape. When the exact count is known and within the cap, relation is "eq" and value is that exact count. When the count exceeds the cap, relation is "gte" and value is the cap the count was probed against, meaning "the actual count is at least value". The cap is COUNT_CAP for every wire-facing endpoint; internal guard paths probe against their own cap, so value carries whatever cap produced it.
    - `value` integer, required — The count value; capped at the probe's cap (10,000 on the wire).
    - `relation` 'eq' | 'gte', required — "eq" means value is the exact count. "gte" means the actual count is at least value (the cap).

## Other responses

- `404` — City not found
- `422` — Invalid city ID format

---

[API](https://skmtc.net/shovels/apis/the-shovels-api-v2.md) · [All operations](https://skmtc.net/shovels/apis/the-shovels-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shovels/the-shovels-api-v2/revisions/d3f0e1f3afa8/schema)