SAsamsara
Beta APIs

[beta] Create a watchpoint

Creates a Ground Intelligence watchpoint for the organization. The submitted location may be snapped to a road within 75 meters. Use the location returned in the response as the saved watchpoint location.

<b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select Write Watchpoints under the Ground Intelligence category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

post/ground-intelligence/watchpoints

Request

  • Base URL
    https://api.samsara.com
  • Auth
    HTTP bearer

Request body

mode'justOnce' | 'daily' | 'weekly' | 'monthly' | 'every15Minutes' | 'hourly' required

Recurrence frequency for observations. Valid values: justOnce, daily, weekly, monthly, every15Minutes, hourly

namestring

Customer-provided name for the watchpoint.

notestring

Customer-provided note about the watchpoint.

observationType'roadDefect' | 'utilityCut' | 'guardrail' | 'streetlight' | 'signage' | 'stormDrain' | 'graffiti' | 'vegetation' | 'blight' | 'illegalDumping' | 'littering' | 'highVegetationWeeds' | 'fire' | 'other' required

Type of condition to observe at this watchpoint. Valid values: roadDefect, utilityCut, guardrail, streetlight, signage, stormDrain, graffiti, vegetation, blight, illegalDumping, littering, highVegetationWeeds, fire, other

sendDashboardNotificationboolean

Sends the authenticated user a dashboard notification for each new observation. Defaults to false. Ignored when the API token is not associated with a user.

Example request

{
  "bearingRange": {
    "endDegrees": 270,
    "startDegrees": 90
  },
  "customDetections": [
    {
      "query": "Only flag work zones with visible workers wearing high-visibility clothing.",
      "type": "workZone"
    }
  ],
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "mode": "daily",
  "name": "Market Street watchpoint",
  "note": "Monitor the intersection for road defects.",
  "observationType": "roadDefect"
}

Response

OK response.

Example response

{
  "data": {
    "bearingRange": {
      "endDegrees": 270,
      "startDegrees": 90
    },
    "createdAtTime": "2026-07-15T10:00:00Z",
    "customDetections": [
      {
        "query": "Only flag work zones with visible workers wearing high-visibility clothing.",
        "type": "workZone"
      }
    ],
    "id": "2eb0e68c-d728-4d2f-b9a0-8bc6ded86422",
    "lastObservationTime": "2019-06-13T19:08:25Z",
    "location": {
      "latitude": 37.7749,
      "longitude": -122.4194
    },
    "mode": "daily",
    "monitoringEndTime": "2026-08-14T10:00:00Z",
    "monitoringStartTime": "2026-07-15T10:00:00Z",
    "name": "Market Street watchpoint",
    "note": "Monitor the intersection for road defects.",
    "observationCount": 1,
    "observationType": "roadDefect",
    "samsaraDashboardUrl": "https://cloud.samsara.com/o/123456/fleet/ground-intelligence?tab=monitors&monitorId=2eb0e68c-d728-4d2f-b9a0-8bc6ded86422",
    "status": "active",
    "updatedAtTime": "2026-07-15T10:00:01Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.