---
updatedAt: 2026-08-19T12:42:10.000Z
agentTools:
  projectIndex: https://docs.delivr.ai/llms.txt
---

# Query events (web_event)

Base event columns only, with no identity resolution. The cheapest tier, and the one to use for volume, scoping and trend work.

Bills the `web_event` meter. The route fixes both the price and the field set, so what a call costs is legible before you make it.

Selecting a field above this tier is rejected with a `400` naming the field and the tier that carries it, rather than being silently dropped or silently billed higher. Call this tier's `/schema` route to see exactly which fields it admits: the allowed set is derived from the event schema and the billing catalogue, so a field that becomes billable leaves the cheaper tiers automatically.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Events & Identity",
    "description": "Query the resolved on-domain events your pixel captures, and resolve identities for the people behind them. Once your pixel is installed (see **Pixel Tracking**), use these endpoints to pull page views, clicks, and other events with the resolved person and company attached, inspect the event schema, resolve hashed emails (HEM), and look up a contact.\n\n**Pick a tier, and you pick the price.** Events are read through four tier routes rather than one endpoint. Each route returns the columns at or below its enrichment tier and bills the matching meter, so the cost of a call is legible from its URL before you make it. Start at `web_event`, which carries no identity resolution and is the cheapest way to establish volume or scope a window, and move up only for the identity fields you actually need.\n\n**Authentication:** organization API key. Send `X-Api-Key` + `X-Api-Secret` on every request. (Legacy JWT bearer auth still works but is deprecated.)\n\n**Base URL:** `https://api.delivr.ai`\n",
    "version": "1.0",
    "contact": {
      "name": "Delivr.ai Support",
      "url": "https://delivr.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.delivr.ai",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": [],
      "ApiSecretAuth": []
    }
  ],
  "tags": [
    {
      "name": "Events",
      "description": "Query on-domain pixel events through the tier routes, with filtering, pagination and projection. The route sets both the billable meter and the fields it can return."
    }
  ],
  "paths": {
    "/api/v3/events/web_event": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Query events (web_event)",
        "operationId": "queryEventsWebEvent",
        "description": "Base event columns only, with no identity resolution. The cheapest tier, and the one to use for volume, scoping and trend work.\n\nBills the `web_event` meter. The route fixes both the price and the field set, so what a call costs is legible before you make it.\n\nSelecting a field above this tier is rejected with a `400` naming the field and the tier that carries it, rather than being silently dropped or silently billed higher. Call this tier's `/schema` route to see exactly which fields it admits: the allowed set is derived from the event schema and the billing catalogue, so a field that becomes billable leaves the cheaper tiers automatically.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/Source"
          },
          {
            "$ref": "#/components/parameters/PixelId"
          },
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "$ref": "#/components/parameters/CampaignId"
          },
          {
            "$ref": "#/components/parameters/StartMs"
          },
          {
            "$ref": "#/components/parameters/EndMs"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Offset"
          },
          {
            "$ref": "#/components/parameters/Select"
          },
          {
            "$ref": "#/components/parameters/Filter"
          },
          {
            "$ref": "#/components/parameters/Distinct"
          },
          {
            "$ref": "#/components/parameters/IncludeCold"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching events, projected to this tier.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query, or a `select` naming a field above this tier."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "$ref": "#/components/responses/PlatformCapRefused"
          },
          "500": {
            "description": "Query failed."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "Organization API key (`dlvr_` prefixed), created in the dashboard at `https://app.delivr.ai/{org_id}/settings/api-keys`. Must be paired with the `X-Api-Secret` header."
      },
      "ApiSecretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Secret",
        "description": "Secret half of the organization API key, paired with `X-Api-Key`. Both headers are required on every request."
      }
    },
    "schemas": {
      "EventsResponse": {
        "type": "object",
        "properties": {
          "index_name": {
            "type": "string",
            "description": "The index used for the query (e.g. `project_id` or `pixel_id`)."
          },
          "index_value": {
            "type": "string",
            "description": "The value of the index used for the query."
          },
          "start_ms": {
            "type": "integer",
            "format": "int64",
            "description": "Start timestamp echoed from the request."
          },
          "end_ms": {
            "type": "integer",
            "format": "int64",
            "description": "End timestamp echoed from the request."
          },
          "limit": {
            "type": "integer",
            "description": "Limit echoed from the request."
          },
          "offset": {
            "type": "integer",
            "description": "Offset echoed from the request."
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Result rows as JSON objects. Fields depend on the `select` parameter."
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "ResponseMeta": {
        "type": "object",
        "required": [
          "files_scanned",
          "buckets_scanned",
          "took_ms"
        ],
        "properties": {
          "files_scanned": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of parquet files scanned."
          },
          "buckets_scanned": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of storage buckets that contained matching data."
          },
          "took_ms": {
            "type": "integer",
            "minimum": 0,
            "description": "Query execution time in milliseconds."
          }
        }
      },
      "PlatformCapRefusal": {
        "type": "object",
        "description": "The body of a platform cap refusal (HTTP 429).",
        "required": [
          "error",
          "kind",
          "message",
          "meter",
          "reason"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "platform_cap_exceeded"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "limit_reached",
              "request_too_large",
              "shut_off"
            ],
            "description": "What retrying can achieve. `limit_reached` succeeds after `resets_at`; `request_too_large` cannot succeed at the current limit; `shut_off` needs support."
          },
          "message": {
            "type": "string",
            "description": "A sentence for your users naming the limit and what to do. It contains no usage figures."
          },
          "meter": {
            "type": "string",
            "description": "The usage meter whose limit refused the request, for example `web_event`."
          },
          "reason": {
            "type": "string",
            "enum": [
              "daily",
              "monthly",
              "off"
            ],
            "description": "The limit that refused the request, or `off` with `shut_off`. For `limit_reached` with both limits used up, the monthly one, which resets last."
          },
          "resets_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the limit resets, in UTC: the next midnight for `daily`, the 1st of next month for `monthly`. Present only for `limit_reached`."
          }
        }
      }
    },
    "parameters": {
      "Source": {
        "name": "source",
        "in": "query",
        "description": "Event source type: `pixel` or `dsp`. Defaults to `pixel` if omitted.",
        "schema": {
          "type": "string",
          "enum": [
            "pixel",
            "dsp"
          ],
          "default": "pixel"
        },
        "example": "pixel"
      },
      "PixelId": {
        "name": "pixel_id",
        "in": "query",
        "description": "Pixel identifier. Use with `source=pixel`.",
        "schema": {
          "type": "string"
        }
      },
      "ProjectId": {
        "name": "project_id",
        "in": "query",
        "description": "Project identifier. Queries all pixels in the project (`source=pixel`). Also required alongside `campaign_id` for Bearer token auth (`source=dsp`).",
        "schema": {
          "type": "string"
        }
      },
      "CampaignId": {
        "name": "campaign_id",
        "in": "query",
        "description": "Campaign identifier. Use with `source=dsp`. Bearer token auth requires `project_id` alongside `campaign_id`.",
        "schema": {
          "type": "string"
        }
      },
      "StartMs": {
        "name": "start_ms",
        "in": "query",
        "description": "Inclusive start timestamp in milliseconds since epoch.",
        "schema": {
          "type": "integer",
          "format": "int64"
        }
      },
      "EndMs": {
        "name": "end_ms",
        "in": "query",
        "description": "Inclusive end timestamp in milliseconds since epoch.",
        "schema": {
          "type": "integer",
          "format": "int64"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "description": "Maximum number of rows to return.",
        "schema": {
          "type": "integer",
          "minimum": 1
        },
        "example": 100
      },
      "Offset": {
        "name": "offset",
        "in": "query",
        "description": "Number of rows to skip before returning results.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "Select": {
        "name": "select",
        "in": "query",
        "description": "Comma-separated column list to project specific fields.",
        "schema": {
          "type": "string"
        }
      },
      "Filter": {
        "name": "filter",
        "in": "query",
        "description": "Filter expression using `<field>:<op>:<value>` syntax.",
        "schema": {
          "type": "string"
        }
      },
      "Distinct": {
        "name": "distinct",
        "in": "query",
        "description": "Comma-separated list of fields to deduplicate the result set.",
        "schema": {
          "type": "string"
        }
      },
      "IncludeCold": {
        "name": "include_cold",
        "in": "query",
        "description": "When `true`, also read date partitions older than the event store's local retention window from cold storage (S3), and allow a longer time window. Works for any source (`pixel` or `dsp`). Off by default.",
        "schema": {
          "type": "boolean",
          "default": false
        },
        "example": true
      }
    },
    "responses": {
      "PlatformCapRefused": {
        "description": "Too many requests: the platform cap refused the request, or it was rate limited.\n\nA platform cap refusal has `error` set to `platform_cap_exceeded`. Accounts have a daily and a monthly usage limit per meter, and `kind` says what retrying can achieve:\n\n- `limit_reached`: this request would take usage past the limit. The same request succeeds once the limit resets at `resets_at`, which `Retry-After` gives in seconds.\n- `request_too_large`: this request alone is larger than the limit, so retrying cannot succeed. Make it smaller (a lower `limit`, or fewer `emails`), or contact support to raise the limit.\n- `shut_off`: usage is paused for this account. Contact support.\n\n`message` says the same in a sentence you can show your users.\n\nAny other 429 is rate limiting: wait for `Retry-After` when it is present, then retry.\n",
        "headers": {
          "Retry-After": {
            "description": "For a platform cap refusal, whole seconds until `resets_at`, rounded up. Sent with `limit_reached` only.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PlatformCapRefusal"
            },
            "example": {
              "error": "platform_cap_exceeded",
              "kind": "limit_reached",
              "message": "You have reached your daily usage limit for Events / Journey. It resets at midnight UTC. Contact support to raise it.",
              "meter": "web_event",
              "reason": "daily",
              "resets_at": "2026-10-05T00:00:00Z"
            }
          }
        }
      }
    }
  }
}
```