> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Log event

> Send outcome or marketing events to an advertiser for measurement

`POST /api/v2/buyer/advertisers/{advertiserId}/log-event`

Sends up to 10,000 outcome or marketing events in a single call, scoped to an `event_source_id` previously registered via [Sync event sources](/v2/buyer/event-sources/tasks/sync-event-sources). Events are deduplicated by `event_id` + `event_type` + `event_source_id`, so retries are safe.

<Warning>
  Never send raw PII. Use only pre-hashed identifiers (SHA-256, lowercase,
  64-char hex) or pre-resolved identity tokens. See the
  [Conversion API guide](/v2/integrations/conversion-api) for hashing rules.
</Warning>

## Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.apostra.com/api/v2/buyer/advertisers/12345/log-event \
    -H "Authorization: Bearer $SCOPE3_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "event_source_id": "website_pixel",
      "events": [
        {
          "event_id": "order_12345",
          "event_type": "purchase",
          "event_time": "2026-01-15T14:30:00Z",
          "action_source": "website",
          "event_source_url": "https://shop.example.com/checkout/complete",
          "user_match": {
            "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
            "click_id_type": "sc3clid"
          },
          "custom_data": { "value": 99.99, "currency": "USD", "order_id": "order_12345" }
        }
      ]
    }'
  ```
</CodeGroup>

## Parameters

| Field | Type | Required | Notes |
| - | - | - | - |
| `advertiserId` | string | Yes | Path. Owning advertiser |
| `event_source_id` | string | Yes | Must match a source registered on the advertiser |
| `events` | object\[] | Yes | 1–10,000 events |
| `events[].event_id` | string | Yes | Dedup key, unique within `event_type` + `event_source_id` |
| `events[].event_type` | enum | Yes | ADCP event type, such as `purchase`, `lead`, `add_to_cart`, `refund`, `subscribe`, `start_trial`, `app_install`, or `custom` |
| `events[].event_time` | string | Yes | ISO 8601 timestamp when the event occurred |
| `events[].custom_event_name` | string | Conditional | Required when `event_type` is `custom` |
| `events[].action_source` | enum | No | `website`, `app`, `in_store`, `phone_call`, `system_generated`, `other` |
| `events[].event_source_url` | string | Conditional | Recommended when `action_source` is `website` |
| `events[].user_match` | object | No | Identity fields: `hashed_email`, `hashed_phone`, `click_id` + `click_id_type`, `uids`, `client_ip`, `client_user_agent` |
| `events[].custom_data` | object | No | `value`, `currency`, `order_id`, `content_ids`, `num_items`, `contents`. If the event source has declared `valueCurrencies` (see [Sync event sources](/v2/buyer/event-sources/tasks/sync-event-sources)), every event carrying `value` must also carry a `currency` from that list — the whole call is rejected otherwise |
| `test_event_code` | string | No | Marks the request as test traffic — validated but excluded from production data |

## Response

```json theme={null}
{
  "events_received": 1,
  "events_processed": 1,
  "partial_failures": [],
  "warnings": [],
  "match_quality": 0.87
}
```

A `200` with `partial_failures` is normal — bad events are rejected individually while the rest succeed. Each failure carries `event_id`, `code`, and `message`. Treat a failure as something to fix at source, not a transient error.

## Errors

* `400 VALIDATION_ERROR` — empty `events`, more than 10,000 events, missing `custom_event_name` on a `custom` event, an `event_type` the source doesn't accept, or (when the source has declared `valueCurrencies`) a monetary event with a missing or unlisted `currency`.
* `404 NOT_FOUND` — `advertiserId` does not exist, or `event_source_id` is not registered on the advertiser.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Event source tasks" href="/v2/buyer/event-sources/tasks" icon="list-check">
    All event source operations
  </Card>

  <Card title="Log Events guide" href="/v2/guides/log-events" icon="circle-dot">
    Event types, identity fields, and best practices
  </Card>

  <Card title="Conversion API" href="/v2/integrations/conversion-api" icon="bolt">
    Identity-hashing rules and attribution methods
  </Card>

  <Card title="Sync event sources" href="/v2/buyer/event-sources/tasks/sync-event-sources" icon="arrows-rotate">
    Register a source before logging
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.