Get Filtered Metrics By Contractor Id

Returns contractor monthly metrics filtered by contractor ID, property type, and tags. Metrics include permit count, average duration, and average pass rate.

GET /contractors/{id}/metrics

Try it

Get Filtered Metrics By Contractor Id

cURL

curl --request GET \
  --url https://api.shovels.ai/v2/contractors/{id}/metrics \
  --header 'X-API-Key: <api-key>'

200

{
  "items": [
    {
      "date": "2023-12-25",
      "tag": "<string>",
      "property_type": "<string>",
      "permit_count": 123,
      "avg_job_value": 123,
      "total_job_value": 123,
      "avg_construction_duration": 123,
      "avg_inspection_pass_rate": 123
    }
  ],
  "size": 123,
  "next_cursor": "<string>"
}

Authorizations

X-API-Key · string · header · required

Path Parameters

id · string · required

Filter by the specified contractor 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 | null

Cursor for pagination

size · integer · default: 50

Required range: 1 <= x <= 100

Response

200

application/json

Contractor monthly metrics

Schema for cursor-paginated contractors metrics response.

items · ContractorsMetricsMonthlyRead · object[] · required

The list of items returned in the response following given criteria.

Show child attributes

items. date · string<date> · required

The month for which the metrics are calculated

items. tag · string | null · required

Specific tag or category for the metrics

items. property_type · string | null

Type of property (e.g., residential, commercial)

items. permit_count · integer | null

Total number of permits issued

items. avg_job_value · integer | null

The average job value of all permits in cents (integer value representing dollars × 100).

items. total_job_value · integer | null

Total value of all jobs/permits in cents (integer value representing dollars × 100)

items. avg_construction_duration · integer | null

Average duration of construction projects in days

items. avg_inspection_pass_rate · integer | null

Average pass rate for inspections (percentage in integer format 0-100)

size · integer · required

The number of items returned in the response.

next_cursor · string | null · required

The cursor for retrieving the next page of results.