Reference

Analytics

Analytics: 4 operations (analytics.ab_comparison, analytics.funnel, analytics.overview, analytics.setter).

Method	Path	Operation
`GET`	`/v1/analytics/ab-comparison`	analytics.ab_comparison
`GET`	`/v1/analytics/funnel`	analytics.funnel
`GET`	`/v1/analytics/overview`	analytics.overview
`GET`	`/v1/analytics/setter`	analytics.setter

analytics.ab_comparison

GET/v1/analytics/ab-comparison

Reply performance compared across campaigns, templates or niches, with comparability findings.

The report the app's comparison panel reads. scope is what a denominator counts (a lead reached by the sequence, or by one step), dimension what separates the arms; templates compare only at step scope. Pass arms (2 to 4 keys from options) to compose the experiment. Rates are reweighted over the reps in scope; a key restricted to reps must pass rep_id.

Operation id	`analytics.ab_comparison`
Scopes	`analytics:read`
Rate class	`heavy`
Idempotency	Not applicable
Keys	Developer keys
Reps	A key restricted to reps sees only data of its own reps

Query parameters

Name	Type	Required	Description
`scope`	`"sequence" \| "step"`	no
`dimension`	`"campaign" \| "template" \| "niche"`	no
`step_order`	`integer`	no	1 to 50
`niche`	`string`	no	at most 200 characters
`days`	`integer`	no	Rolling window in days. Absent: all time.. 1 to 3650
`include_breakup`	`boolean`	no
`arms`	`string[]`	no	Arm keys from `options`, repeated or as one comma-separated value.. at most 8 items
`rep_id`	`uuid`	no	A rep (connected Instagram account) id.

Response 200

Field	Type	Required
`dimension`	`"campaign" \| "template" \| "niche"`	yes
`experiment`	`object \| null`	yes
`findings`	`object[]`	yes
`options`	`object[]`	yes
`scope`	`"sequence" \| "step"`	yes

Errors

Status	Code	When
400	`COMPARISON_QUERY_INVALID_400`	The combination is not comparable (for example templates at sequence scope, or step scope without step_order); `reason` names the rule.
403	`API_REP_RESTRICTED_403`	A key restricted to reps asked for workspace-level numbers, which include other reps' traffic. Pass one of the key's reps as rep_id.
404	`REP_NOT_FOUND_404`	The rep does not exist in this workspace, is archived, or is outside the key's rep restriction.

Every operation can also answer the shared errors: authentication, scopes, rate limits and validation.

Example

bash

curl "https://api.dmhero.ai/v1/analytics/ab-comparison" \
  -H "Authorization: Bearer $DMHERO_API_KEY"

JSON Schema

Response 200

{
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "sequence",
        "step"
      ]
    },
    "dimension": {
      "type": "string",
      "enum": [
        "campaign",
        "template",
        "niche"
      ]
    },
    "options": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "reached": {
            "type": "number"
          }
        },
        "required": [
          "key",
          "label",
          "reached"
        ],
        "additionalProperties": false
      }
    },
    "experiment": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "detail": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          }
        },
        "required": [
          "code",
          "severity",
          "detail"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "scope",
    "dimension",
    "options",
    "experiment",
    "findings"
  ],
  "additionalProperties": false
}

analytics.funnel

GET/v1/analytics/funnel

The lead status funnel and the daily cohort series of first DMs.

Workspace-level, so a key restricted to reps is refused.

Operation id	`analytics.funnel`
Scopes	`analytics:read`
Rate class	`read`, costs 5 per call
Idempotency	Not applicable
Keys	Developer keys
Reps	A key restricted to reps sees only data of its own reps

Query parameters

Name	Type	Required	Description
`days`	`integer`	no	Reporting window in days, over each lead's first DM. Default 30.. 1 to 3650

Response 200

Field	Type	Required
`cohort`	`object[]`	yes
`period`	`object`	yes
`stages`	`object[]`	yes

Errors

Status	Code	When
403	`API_REP_RESTRICTED_403`	A key restricted to reps asked for workspace-level numbers, which include other reps' traffic. Pass one of the key's reps as rep_id.

Every operation can also answer the shared errors: authentication, scopes, rate limits and validation.

Example

bash

curl "https://api.dmhero.ai/v1/analytics/funnel" \
  -H "Authorization: Bearer $DMHERO_API_KEY"

JSON Schema

Response 200

{
  "type": "object",
  "properties": {
    "period": {
      "type": "object",
      "properties": {
        "days": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "days"
      ],
      "additionalProperties": false
    },
    "stages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "count": {
            "type": "number"
          }
        },
        "required": [
          "status",
          "count"
        ],
        "additionalProperties": false
      }
    },
    "cohort": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "day": {
            "type": "string"
          },
          "reached": {
            "type": "number"
          },
          "replied": {
            "type": "number"
          },
          "converted": {
            "type": "number"
          }
        },
        "required": [
          "day",
          "reached",
          "replied",
          "converted"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "period",
    "stages",
    "cohort"
  ],
  "additionalProperties": false
}

analytics.overview

GET/v1/analytics/overview

Headline numbers: leads, reach, replies and conversions, plus the reps' threads and today's sends.

stats and outreach_funnel are workspace-level (leads are shared by every rep), so a key restricted to reps must pass rep_id and gets them as null. reps covers rep_id when given, else every rep the key may act as.

Operation id	`analytics.overview`
Scopes	`analytics:read`
Rate class	`read`, costs 5 per call
Idempotency	Not applicable
Keys	Developer keys
Reps	A key restricted to reps sees only data of its own reps

Query parameters

Name	Type	Required	Description
`days`	`integer`	no	Reporting window in days, over each lead's first DM. Default 30.. 1 to 3650
`rep_id`	`uuid`	no	A rep (connected Instagram account) id.

Response 200

Field	Type	Required
`outreach_funnel`	`object \| null`	yes
`period`	`object`	yes
`reps`	`object`	yes
`stats`	`object \| null`	yes

Errors

Status	Code	When
403	`API_REP_RESTRICTED_403`	A key restricted to reps asked for workspace-level numbers, which include other reps' traffic. Pass one of the key's reps as rep_id.
404	`REP_NOT_FOUND_404`	The rep does not exist in this workspace, is archived, or is outside the key's rep restriction.

Every operation can also answer the shared errors: authentication, scopes, rate limits and validation.

Example

bash

curl "https://api.dmhero.ai/v1/analytics/overview" \
  -H "Authorization: Bearer $DMHERO_API_KEY"

JSON Schema

Response 200

{
  "type": "object",
  "properties": {
    "period": {
      "type": "object",
      "properties": {
        "days": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "days"
      ],
      "additionalProperties": false
    },
    "stats": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "total_leads": {
              "type": "number"
            },
            "contacted": {
              "type": "number"
            },
            "replied": {
              "type": "number"
            },
            "converted": {
              "type": "number"
            },
            "not_interested": {
              "type": "number"
            },
            "reply_rate": {
              "type": "number"
            },
            "conversion_rate": {
              "type": "number"
            }
          },
          "required": [
            "total_leads",
            "contacted",
            "replied",
            "converted",
            "not_interested",
            "reply_rate",
            "conversion_rate"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "outreach_funnel": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "reached": {
              "type": "number"
            },
            "replied": {
              "type": "number"
            },
            "converted": {
              "type": "number"
            },
            "reply_rate": {
              "type": "number"
            },
            "conversion_rate": {
              "type": "number"
            }
          },
          "required": [
            "reached",
            "replied",
            "converted",
            "reply_rate",
            "conversion_rate"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "reps": {
      "type": "object",
      "properties": {
        "rep_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          }
        },
        "conversations": {
          "type": "object",
          "properties": {
            "total": {
              "type": "number"
            },
            "unread": {
              "type": "number"
            }
          },
          "required": [
            "total",
            "unread"
          ],
          "additionalProperties": false
        },
        "today": {
          "type": "object",
          "properties": {
            "sent": {
              "type": "number"
            },
            "skipped": {
              "type": "number"
            },
            "not_interested": {
              "type": "number"
            }
          },
          "required": [
            "sent",
            "skipped",
            "not_interested"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "rep_ids",
        "conversations",
        "today"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "period",
    "stats",
    "outreach_funnel",
    "reps"
  ],
  "additionalProperties": false
}

analytics.setter

GET/v1/analytics/setter

The AI Setter report for one rep: variants, funnel, turns, follow-ups, silence, segments, objections.

The report the app's setter Analytics tab draws, per rep. days limits it to threads first contacted inside the window, variant_id to one setter variant.

Operation id	`analytics.setter`
Scopes	`analytics:read`
Rate class	`read`, costs 5 per call
Idempotency	Not applicable
Keys	Developer keys
Reps	A key restricted to reps sees only data of its own reps

Query parameters

Name	Type	Required	Description
`rep_id`	`uuid`	yes	A rep (connected Instagram account) id.
`days`	`integer`	no	Threads first contacted in the last N days. Absent: all time.. 1 to 3650
`variant_id`	`uuid`	no

Response 200

Field	Type	Required
`depth`	`object \| null`	yes
`emerging_objections`	`object[]`	yes
`followup`	`object`	yes
`funnel`	`object`	yes
`metrics`	`object[]`	yes
`objection_flow`	`object[]`	yes
`recommendation`	`object`	yes
`rep_id`	`uuid`	yes
`segments`	`object`	yes
`silence`	`object`	yes
`totals`	`object`	yes
`turns`	`object`	yes

Errors

Status	Code	When
404	`REP_NOT_FOUND_404`	The rep does not exist in this workspace, is archived, or is outside the key's rep restriction.

Every operation can also answer the shared errors: authentication, scopes, rate limits and validation.

Example

bash

curl "https://api.dmhero.ai/v1/analytics/setter?rep_id=3f6c2a9e-8b1d-4c7a-9e2f-5d4b3a2c1e0f" \
  -H "Authorization: Bearer $DMHERO_API_KEY"

JSON Schema

Response 200

{
  "type": "object",
  "properties": {
    "rep_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "metrics": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "totals": {
      "type": "object",
      "properties": {
        "engaged": {
          "type": "number"
        },
        "replied": {
          "type": "number"
        },
        "booked": {
          "type": "number"
        }
      },
      "required": [
        "engaged",
        "replied",
        "booked"
      ],
      "additionalProperties": false
    },
    "funnel": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "turns": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "followup": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "silence": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "segments": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "objection_flow": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "emerging_objections": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "recommendation": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "depth": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "rep_id",
    "metrics",
    "totals",
    "funnel",
    "turns",
    "followup",
    "silence",
    "segments",
    "objection_flow",
    "emerging_objections",
    "recommendation",
    "depth"
  ],
  "additionalProperties": false
}