occurred_at in UTC (ISO 8601) and occurred_at_local in the account’s time zone.
Audience overview
fanaura.audience_overview returns contact totals. No parameters.
object
string
For example, “You have 412 contacts, including 37 new this week.”
Search contacts
fanaura.search_contacts finds or ranks contacts. Each card holds the summary, identity fields, and the three newest timeline events. For the full story, call get_contact.
string
A fragment of a name, email, phone, or Instagram handle.
object
Map of field key to exact value, such as
{ "city": "Austin" }. Keys come from describe_contact_fields. Computed fields cannot be filtered.string
default:"created_at"
A stored field key to sort by.
'newest' | 'oldest'
default:"newest"
Sort direction.
number
default:"20"
Page size, from 1 to 50.
string
The
next_cursor from the previous page.string
Only contacts who visited this journey’s link.
string
Stored source code, such as
instagram_dm.string
ISO 8601. Contacts created at or after this time.
string
ISO 8601. Contacts created at or before this time.
number
Only contacts with at least this many link visits.
boolean
true to rank contacts by journey link visits. Uses limit, default 5, and ignores the other filters.object[]
string | null
Pass this back as
cursor for the next page. null on the last page.Get contact
fanaura.get_contact returns one contact in full. Pass exactly one lookup.
string
Fanaura contact UUID.
string
Instagram handle, with or without
@.string
Phone number as stored.
string
Email address. Case does not matter.
'oldest' | 'newest'
default:"oldest"
Timeline order.
string
required
A paragraph written from the contact’s data: who they are, when they joined, how they found you, where they were, what they told you, how to reach them, and their engagement.
object
Field groups. Only fields with a value appear. Each field is
{ label, value, provenance }, plus local for timestamps.object
required
object[]
required
Every event. See the event shape.
Contact timeline
fanaura.contact_timeline pages through a long history, 50 events at a time.
string
required
Fanaura contact UUID.
string
ISO 8601. Events at or after this time.
string
ISO 8601. Events at or before this time.
string[]
Event types to keep, such as
["link_returned", "journey_submitted"].'oldest' | 'newest'
default:"oldest"
Event order.
string
The
next_cursor from the previous page.object[]
Up to 50 events.
string | null
The next page, or
null.Event shape
string
Stable event ID.
string
Event type from the table below.
string
Plain action, such as “Came back to your link”.
string
ISO 8601 in UTC.
string
The same time in the account’s time zone.
object | null
{ id, name } when the event belongs to a journey.string | null
How the contact reached you, on entry events.
number | null
1 for the first link visit, 2 for the next, and so on.
object[]
Every detail from that moment, as
{ label, value }. Link visits include place, referring site, the app they came from, device, language, and “Visit 2 of 5”. Journey submissions include each answer.Audience activity
fanaura.audience_activity counts activity across the whole audience. It returns numbers, not people.
string
ISO 8601 start of the range.
string
ISO 8601 end of the range.
string
A stored field key to break down, such as
city or vip_status.object[]
{ key: "2026-09-14", count: 12 }, largest first.object[]
Counts by event label.
object[]
Link visits by journey ID.
object[]
Link visits by the app people came from.
object[]
Link visits by city.
object[]
Link visits by device.
object
Present when
field is passed: { field, values }.boolean
true when a range held more than 5,000 rows. Narrow the range for exact counts.Describe contact fields
fanaura.describe_contact_fields lists every field Fanaura can hold, with contacts_with_value for stored fields, and every event type. Use it to answer “What can I know about my fans?” No parameters.
object[]
{ key, label, category, type, privacy, provenance, contacts_with_value }. Computed fields return contacts_with_value: null.object[]
{ type, label, sheet }. sheet: true marks the main events shown on a contact’s timeline in the Fanaura iPhone app.Field reference
- Identity
- Reach
- Location and device
- Profile
- Acquisition
- Engagement and more
Event types
The main events, shown on a contact’s timeline in the Fanaura iPhone app:
Other recorded events include
music.presave (Pre-saved a release), qr.scanned (Scanned a QR code), merch.purchased (Bought merch), capture.submitted (Submitted a capture form), fan.email_clicked (Tapped an email link), and sms.link_clicked (Tapped a text link). Call describe_contact_fields for the complete list.
Session tokens, one-time codes, and platform tokens are never returned by any tool. Read Data and privacy.