Get Performance Metrics

Get outreach performance metrics: time-series trends and/or conversion funnel.

Set view='timeseries' for daily counts of a single metric (contacts/people/replies/meetings). Set view='funnel' for aggregate conversion data: contacted->replied->met funnel with rates, reply rates by channel, and LinkedIn pipeline breakdown. Set view='both' for everything in one call.

For T1s sent over time: view='timeseries', metric='contacts'. For reply rate and funnel: view='funnel'. Operators: pass for_company to get metrics for a specific client.

UNIT CONVENTIONS USED IN RESPONSES Every count field is one of {messages, unique_people, plans, campaigns, days}; see the Returns block for the unit attached to each field. Note that timeseries 'contacts' and funnel.contacted are BOTH unique_people (i.e. unique people, deduped per person_id), NOT message counts.

DATE-FILTER COLUMN PER METRIC (timeseries)

• metric='people': filters on company_people.created_at — start_date / end_date
• metric='contacts': filters on messages.sent_at (sequence_number=1 only) — start_date / end_date
• metric='replies': filters on company_people.replied_at — start_date / end_date
• metric='meetings': filters on outcomes.observed_at (meeting_booked / meeting_held attributed to an outreach send) — start_date / end_date ONE SOURCE FOR MEETINGS: funnel.meetings, stage_funnel.meetings_all and the 'meetings' timeseries read the same outcomes ledger under the same attribution rule. They differ only in the clock: the funnel windows on the SEND (people sent in the window who met, whenever), the timeseries on the MEETING (people whose meeting fell in the window). A meeting with a person no outreach send reached is in neither. reply_rates_by_channel and stage_funnel share one scope per response mode — the stage funnel is derived from the same per-channel counts, never from a separate query.

Returns (selected fields, with unit + scope + date-filter annotations): view (str): Echoes the requested view.

timeseries (object, when view='timeseries' or 'both'):
    metric (str): The metric name.
    data (list of {date, count}):
        date (str): YYYY-MM-DD.
        count (int): unit = unique_people for ALL four metrics (T1-sent dedupe by
        person; company_people rows for people/replies; for meetings, each person
        once per window at their first meeting outcome in it).

funnel (object, when view='funnel' or 'both'):
    total_people (int, unit=unique_people, scope=non-archived company_people in
        tenant, no date filter): denominator for contact_rate.
    contacted (int, unit=unique_people, scope=non-archived; date-filter:
        company_people.last_message_sent_at): distinct people with at least one
        sent message in window. NOT the total message count.
    replied (int, unit=unique_people, scope=non-archived; date-filter:
        company_people.replied_at): distinct people who replied. NOT the total
        reply-message count.
    meetings (int, unit=unique_people, scope=includes archived; date-filter:
        the send's messages.sent_at): send-cohort people with a meeting_booked /
        meeting_held outcome, whenever observed. Equal to stage_funnel.meetings_all.
        A meeting is a permanent positive outcome so it counts regardless of
        archive state.
    summary (str): human prose summary of the funnel.

conversion_rates (object): contact_rate, reply_rate, meeting_rate, booking_rate
    — percentages computed from the funnel counts above, NOT independent measures.

reply_rates_by_channel (list, when view='funnel' or 'both'):
    One entry per channel actually used. Per-channel entries (unit=unique_people
    for sent/replied/accepted):
    - 'linkedin_connection': sent + accepted + acceptance_rate (NOT a reply_rate;
      connection requests are top-of-funnel, replies happen on follow-up DMs).
      note: "Acceptance rate, not reply rate. Replies happen on follow-up messages."
      accepted counts DISTINCT cohort people with a connection_accepted
      OUTCOME on the cohort send's action (webhook-observed or
      reply-inferred; organic connections have no cohort send and are
      structurally excluded).
    - 'linkedin_message': sent + replied + reply_rate (follow-up DMs sent to
      connected people).
    - 'email': sent + replied + reply_rate.
    - 'linkedin_inmail': sent + replied + reply_rate.

stage_funnel (object, when view='funnel' or 'both'):
    VRU-862 M3.4: derived with reply_rates_by_channel from ONE
    spine cohort projection (actions × outcomes), so the sections
    agree by construction. The frame is COHORT-scoped: the
    population is the outreach sends in the window (messages.sent_at;
    status sent/replied/bounced — bounced sends count as sent), and
    every later stage is a subset of that cohort via its actions'
    outcome rows, whenever observed. No rate can exceed 100%.
    Objective scoping keys on the send's own authoring objective
    (messages.objective_id — VRU-878 PR B; a legacy campaign is an
    objective now). Each rate in
    reply_rates_by_channel also ships a *_detail object carrying
    numerator, denominator, and metric_definition_version, and the
    response includes metric_definitions (the versioned contracts).
    connection_requests_sent (int, unit=unique_people): the
        linkedin_connection send cohort.
    connections_accepted (int, unit=unique_people): cohort members
        with a connection_accepted outcome (webhook-observed or
        reply-inferred; organic connections without a Vruum invite
        cannot appear — they have no cohort send).
    acceptance_rate (float, percent): connections_accepted /
        connection_requests_sent.
    followups_sent (int, unit=unique_people): the linkedin_message
        send cohort.
    followup_replies (int, unit=unique_people): cohort members with
        a STANDING reply outcome (reversals fold out; the outcome's
        observed time is the reply's own, whenever it landed).
    followup_reply_rate (float, percent): of the follow-up DMs SENT
        (NOT of accepted connections).
    meetings (int, unit=unique_people): the cohort's meeting people who
        ALSO hold a standing reply (the numerator of
        reply_to_meeting_rate). meetings_all is every cohort person with
        a meeting outcome (meeting_booked/meeting_held attributed to
        cohort actions, influence sets included) and equals
        funnel.meetings.
    reply_to_meeting_rate (float, percent): a SUBSET rate — cohort
        people with BOTH a standing reply and a meeting outcome, over
        cohort standing repliers; reply_to_meeting_rate_detail carries
        the counts + contract version. Bounded by construction
        (meetings without a reply appear in meetings_all, not here).
    (The response also carries `coverage`: cohort messages without a
    spine action can enter denominators but never numerators —
    coverage.complete=false labels a degraded read honestly.)
    summary (str): human prose summary.
        "Biggest drop:" picks the largest absolute drop among
        (connection_requests_sent - connections_accepted),
        (followups_sent - followup_replies),
        (replied - meetings). This is a raw-count heuristic; it can name
        "connection acceptance" even when the acceptance rate is healthy
        (e.g. 80%) because the absolute drop is still the largest of the three.

connections (object, when view='connections'):
    total_requested (int, unit=plans).
    acceptance_rate (float, percent of plans).
    avg_time_to_accept_hours (float|null).
    withdrawal_rate (float, percent): plans auto-withdrawn / total requested.
    retry_success_rate (float): connected-after-retry / completed-retried plans.
    by_status (object): plan counts keyed by connection_status.