Browse API documentation
API documentation

Events

Manage events for a site.

Search API documentation
    v1

    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.
    Options:dollarpoundeuroyuanpesoshekelyenwonhryvniafrancrupeeintegernone

    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: dollarOptions:dollarpoundeuroyuanpesoshekelyenwonhryvniafrancrupeeintegernone

    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.
    Options:dollarpoundeuroyuanpesoshekelyenwonhryvniafrancrupeeintegernone

    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.