---
agentTools:
  projectIndex: https://developer-docs.gomotive.com/llms.txt
---

# Fetch all the waste pickup events

**Purpose**: The purpose of this endpoint is to give an authenticated company a searchable, paginated list of published waste pickup events within a requested time window. t is the discovery endpoint: you use it to find which pickup events exist before drilling into any one event in detail.

> 🚧 IMPORTANT
>
> This endpoint uses "**OAuth 2.0 Client Credentials authentication through Motive CIAM**". Check out the [Overview - Authentication](https://developer-docs.gomotive.com/reference/overview-wastepickup#authentication) section for more info on generating the access token required to call this endpoint.

> 📘 NOTE
>
> If you do not send `has_overage`, `has_contamination`, or`include_all_pickups`, it returns flagged events only.
>
> Fields such as `thumbnail_url,` `sd_url`, `front_facing_url`, and `rep_frame_url `are presigned Amazon S3 GET URLs. They expire 3 hours after issuance (X-Amz-Expires=10800). Do not cache or persist them; request a fresh list or detail response when URLs expire.

# Response Parameters

### events

* **Type**: Array (Object)
* **Description**: A list of recorded event objects containing details about specific vehicle activities or occurrences.

### offline\_id

* **Type**: String (UUID)
* **Description**: The unique offline identifier assigned to the event.

### type

* **Type**: String
* **Description**: The classification or category of the event (e.g., pickup).

### start\_time

* **Type**: String (Timestamp)
* **Description**: The date and time when the event began, in ISO 8601 format.

### address

* **Type**: String
* **Description**: The physical location or street address where the event took place.

### lat

* **Type**: Float
* **Description**: The geographical latitude coordinate of the event location.

### lon

* **Type**: Float
* **Description**: The geographical longitude coordinate of the event location.

### severity

* **Type**: String
* **Description**: The level of severity associated with the event (e.g., high).

### has\_overage

* **Type**: Boolean
* **Description**: Indicates whether the event involved an overage situation.

### has\_contamination

* **Type**: Boolean
* **Description**: Indicates whether contamination was detected during the event.

### thumbnail\_url

* **Type**: String (URL)
* **Description**: A pre-signed URL pointing to a thumbnail preview image of the event.

### sd\_url

* **Type**: String (URL)
* **Description**: A pre-signed URL pointing to the standard definition video recording of the event.

### driver

* **Type**: Object
* **Description**: Details about the driver assigned to the event, if available.

### vehicle

* **Type**: Object
* **Description**: Details regarding the vehicle associated with the event.

### id

* **Type**: String
* **Description**: The unique identifier for the vehicle.

### number

* **Type**: String
* **Description**: The fleet vehicle or unit number.

### vin

* **Type**: String
* **Description**: The Vehicle Identification Number (VIN).

### model\_source

* **Type**: Array (String)
* **Description**: List of AI or system model sources triggered by the event.

### overage

* **Type**: String
* **Description**: Model source tag indicating overage detection.

### has\_out\_of\_cab

* **Type**: Boolean
* **Description**: Indicates whether an out-of-cab incident or view was flagged during the event.

### rep\_frame\_url

* **Type**: String (URL)
* **Description**: A pre-signed URL pointing to a representative frame image of the event.

### page\_no

* **Type**: Integer
* **Description**: The current page number of the paginated response.

### per\_page

* **Type**: Integer
* **Description**: The maximum number of events returned per page.

### total

* **Type**: Integer
* **Description**: The total number of events matching the query across all pages.

***

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Motive",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.gomotive.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/api/aivision/v2/public/waste/pickups": {
      "get": {
        "summary": "Fetch all the waste pickup events",
        "description": "",
        "operationId": "fetch-all-the-waste-pickup-events",
        "parameters": [
          {
            "name": "start_time",
            "in": "query",
            "description": "Specify the start time for the waste pickup event(s). RFC3339 datetime; inclusive lower bound on pickup start_time.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_time",
            "in": "query",
            "description": "Specify the end time for the waste pickup event. RFC3339 datetime; inclusive upper bound on pickup start_time; must be after start_time.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "description": "Latitude for an approximate 100 m bounding-box filter. Must be provided together with lon.",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "description": "Longitude for an approximate 100 m bounding-box filter. Must be provided together with lat.",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "driver_id",
            "in": "query",
            "description": "Specify either a single or multiple driver IDs, separated by commas.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "vehicle_id",
            "in": "query",
            "description": "Specify either a single or multiple vehicle IDs, separated by commas.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "severity",
            "in": "query",
            "description": "Specify the severity of the event. Allowed values are <ul><li><b>critical</b></li><li><b>high</b></li><li><b>medium</b></li><li><b>low</b></li></ul>",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_overage",
            "in": "query",
            "description": "Specify if the pickup has an overage or not.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "has_contamination",
            "in": "query",
            "description": "Specify if the pickup has contaminated goods.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "include_all_pickups",
            "in": "query",
            "description": "Specify if all the pickups (not only flagged), are to be returned in the response. <ul><li><i>true</i>: Returns all published pickups including flagged pickups.</li><li><i>false</i>: Returns only flagged pickups.</li></ul>",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "group_by",
            "in": "query",
            "description": "Group the response instead of a flat list of pickup events.",
            "schema": {
              "type": "string",
              "enum": [
                "address",
                "vehicle",
                "driver"
              ]
            }
          },
          {
            "name": "sort_field",
            "in": "query",
            "description": "Sort the pickups based on the mentioned criteria. You must also specify the <b>sort_direction</b>, if using this parameter.",
            "schema": {
              "type": "string",
              "enum": [
                "severity",
                "driver_name",
                "start_time"
              ]
            }
          },
          {
            "name": "sort_direction",
            "in": "query",
            "description": "Specify the sort direction for the response.",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Specify the pagination number.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "description": "Specify the number of events in a page.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "  {\n  \"events\": [\n    {\n      \"offline_id\": \"b84ec320-db53-48ec-804f-d979f8c7325c\",\n      \"type\": \"pickup\",\n      \"start_time\": \"2026-05-27T18:50:24.397Z\",\n      \"address\": \"9377 West 75th Street, Overland Park, KS\",\n      \"lat\": 38.99224,\n      \"lon\": -94.694664,\n      \"severity\": \"high\",\n      \"has_overage\": true,\n      \"has_contamination\": false,\n      \"thumbnail_url\": \"https://...thumb.0000000.jpg?X-Amz-Expires=10800&X-Amz-Signature=...\",\n      \"sd_url\": \"https://...h264.mp4?X-Amz-Expires=10800&X-Amz-Signature=...\",\n      \"driver\": null,\n      \"vehicle\": {\n        \"id\": \"3097990\",\n        \"number\": \"936071\",\n        \"vin\": \"1M1AN07Y5JM012345\"\n      },\n      \"model_source\": [\n        \"overage\"\n      ],\n      \"has_out_of_cab\": false,\n      \"rep_frame_url\": \"https://...rep_frame.jpg?X-Amz-Expires=10800&X-Amz-Signature=...\"\n    }\n  ],\n  \"page_no\": 1,\n  \"per_page\": 50,\n  \"total\": 1\n}\n"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "offline_id": {
                            "type": "string",
                            "example": "b84ec320-db53-48ec-804f-d979f8c7325c"
                          },
                          "type": {
                            "type": "string",
                            "example": "pickup"
                          },
                          "start_time": {
                            "type": "string",
                            "example": "2026-05-27T18:50:24.397Z"
                          },
                          "address": {
                            "type": "string",
                            "example": "9377 West 75th Street, Overland Park, KS"
                          },
                          "lat": {
                            "type": "number",
                            "example": 38.99224,
                            "default": 0
                          },
                          "lon": {
                            "type": "number",
                            "example": -94.694664,
                            "default": 0
                          },
                          "severity": {
                            "type": "string",
                            "example": "high"
                          },
                          "has_overage": {
                            "type": "boolean",
                            "example": true,
                            "default": true
                          },
                          "has_contamination": {
                            "type": "boolean",
                            "example": false,
                            "default": true
                          },
                          "thumbnail_url": {
                            "type": "string",
                            "example": "https://...thumb.0000000.jpg?X-Amz-Expires=10800&X-Amz-Signature=..."
                          },
                          "sd_url": {
                            "type": "string",
                            "example": "https://...h264.mp4?X-Amz-Expires=10800&X-Amz-Signature=..."
                          },
                          "driver": {},
                          "vehicle": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "example": "3097990"
                              },
                              "number": {
                                "type": "string",
                                "example": "936071"
                              },
                              "vin": {
                                "type": "string",
                                "example": "1M1AN07Y5JM012345"
                              }
                            }
                          },
                          "model_source": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "example": "overage"
                            }
                          },
                          "has_out_of_cab": {
                            "type": "boolean",
                            "example": false,
                            "default": true
                          },
                          "rep_frame_url": {
                            "type": "string",
                            "example": "https://...rep_frame.jpg?X-Amz-Expires=10800&X-Amz-Signature=..."
                          }
                        }
                      }
                    },
                    "page_no": {
                      "type": "integer",
                      "example": 1,
                      "default": 0
                    },
                    "per_page": {
                      "type": "integer",
                      "example": 50,
                      "default": 0
                    },
                    "total": {
                      "type": "integer",
                      "example": 1,
                      "default": 0
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true,
  "_id": "66acf64a829e88001980fbf2:6a60c76341feeb4faf50c811"
}
```