API reference
Browse API documentation
API reference

Events

Manage events for a site.

List events#

GET/sites/{site_id}/events

Return a list of this site's events: every event name the site has tracked, plus any event you've set a currency for. Events are sorted by name.

Identify events by name. Goal IDs were removed on 24 September 2026, so don't store id. Only use it as the starting_after or ending_before cursor when you page through this list.
currency is the currency you set with Set event currency, or null when the event uses your site's default. created_at is null for newer events.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Query parameters

limitintegeroptional
A limit on the number of objects to be returned, between 1 and 100.
Default 10
starting_afterstringoptional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For example, if you make a list request and receive 10 objects ending with obj_foo, your subsequent call can include starting_after=obj_foo to fetch the next page.
ending_beforestringoptional
A cursor for use in pagination, working in the opposite direction to starting_after. ending_before is an object ID that defines your place in the list.

Returns

A list of event objects.

GET
curl "https://api.usefathom.com/v1/sites/CDBUGS/events" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "object": "list",
    "url": "/v1/sites/CDBUGS/events",
    "has_more": false,
    "data": [
        {
            "id": "IJKLMNOP",
            "object": "event",
            "name": "Purchased product",
            "currency": "pound",
            "created_at": "2020-08-21 15:24:00"
        },
        {
            "id": "ABCDEFGH",
            "object": "event",
            "name": "Signed up to newsletter",
            "currency": null,
            "created_at": "2020-08-21 15:24:00"
        }
    ]
}

Set event currency#

POST/sites/{site_id}/events/currency

Set the currency of an event by its name. You can set it before the event is tracked for the first time: the currency applies as soon as the event arrives.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Body parameters

namestringrequired
The name of the event (up to 255 characters).
Example: Purchase early access
currencystringrequired
The currency used for any value attached to this event's completions.
Optionsdollarpoundeuroyuanpesoshekelyenwonhryvniafrancrupeeintegernone

Returns

Returns an updated object on success. Otherwise, this call returns an error.

POST
curl -X POST "https://api.usefathom.com/v1/sites/CDBUGS/events/currency" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Purchase early access",
    "currency": "pound"
  }'
Response
{
    "object": "event",
    "name": "Purchase early access",
    "currency": "pound",
    "updated": true
}

Delete event#

DELETE/sites/{site_id}/events

Remove the currency you set for an event, so it goes back to your site's default currency. This doesn't delete the event's completion data, so the event still appears in List events while it has data. The call succeeds even if the event has no currency set.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Query parameters

namestringrequired
The name of the event.
Example: Purchase early access

Returns

Returns a deleted object on success. Otherwise, this call returns an error.

DELETE
curl -X DELETE "https://api.usefathom.com/v1/sites/CDBUGS/events?name=Purchase%20early%20access" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "object": "event",
    "name": "Purchase early access",
    "deleted": true
}

Get event#

Deprecated

GET/sites/{site_id}/events/{event_id}

This endpoint is no longer available

This endpoint is no longer available. Use List events.

Previously returned a single event by its goal code. This endpoint is no longer available.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
event_idstringrequired
The id (tracking code) of the event, as returned when the event was created.
Example: ABCDEFGH

Create event#

Deprecated

POST/sites/{site_id}/events

This endpoint is no longer available

This endpoint is no longer available. Track the event on your site, then use List events and Set event currency.

Previously created an event. This endpoint is no longer available.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Body parameters

namestringrequired
The name of the event (up to 255 characters).
Example: Purchase early access
currencystringoptional
The currency used for any value attached to this event's completions. If omitted, defaults to dollar.
Default dollarOptionsdollarpoundeuroyuanpesoshekelyenwonhryvniafrancrupeeintegernone

Update event#

Deprecated

POST/sites/{site_id}/events/{event_id}

This endpoint is no longer available

This endpoint is no longer available. To change an event's currency, use Set event currency.

Previously updated an event by its goal code. This endpoint is no longer available.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
event_idstringrequired
The id (tracking code) of the event you wish to update.
Example: ABCDEFGH

Body parameters

namestringoptional
The name of the event (up to 255 characters).
currencystringoptional
The currency used for any value attached to this event's completions.
Optionsdollarpoundeuroyuanpesoshekelyenwonhryvniafrancrupeeintegernone

Wipe event#

Deprecated

DELETE/sites/{site_id}/events/{event_id}/data

This endpoint is no longer available

This endpoint has been retired and now returns 410 Gone. It is no longer possible to wipe an event's completion data via the API.

Previously wiped all completion data belonging to an event. This endpoint is no longer available.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
event_idstringrequired
The id (tracking code) of the event.

Delete event#

Deprecated

DELETE/sites/{site_id}/events/{event_id}

This endpoint is no longer available

This endpoint is no longer available. To delete an event, use Delete event with the event name.

Previously deleted an event by its goal code. This endpoint is no longer available.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
event_idstringrequired
The id (tracking code) of the event you wish to delete.