Call Reports API

Reports Parameters

GET https://api.retreaver.com/api/v1/reports.json?....

Query Parameters

Swipe horizontally to view full table

Parameter	Mandatory	Description
api_key	Yes	The api_key used to authenticate this request.
company_id	No	Return reports associated to the specific company if you have access to that company. If left blank it defaults to the current company associated with the API key.
domain	Yes	The domain of the report. Currently only `calls`.
facet	Yes	One of: `['number', 'campaign', 'affiliate', 'target', 'date', 'tag_value', 'state']`. This is the object that you will want to generate a report for. For companies with the affiliate marketing feature enabled, `publisher` and `buyer` may be used as aliases for `affiliate` and `target` respectively.
created_at_start	Yes
created_at_end	Yes
page	No	The page of results to return. Defaults to 1.
per_page	No	The number of results per page. Defaults to 25, maximum 100.
tag_value_key	No	When faceting by tag_value you may want to provide a second facet to drill down on. Example

Note

created_at_start must be before created_at_end and the two must be smaller than 2 years apart.

Buyer Calls In Progress Report

curl "https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=buyer&domain=calls&created_at_start=2026-04-22&created_at_end=2026-04-24"

Swipe horizontally for full code

The above command returns JSON structured like this:

{
  "count": 2,
  "count_total": 2,
  "data": [
    {
      "id": 30417,
      "facet_name": "Alex Johnson - +14155551234",
      "total_calls": 5,
      "in_progress_count": 2.0,
      "...": "..."
    },
    {
      "id": 27299,
      "facet_name": "Power Axle - +16476695972",
      "total_calls": 3,
      "in_progress_count": 1.0,
      "...": "..."
    }
  ]
}

Swipe horizontally for full code

Get a report for all calls faceted by buyer. The in_progress_count field indicates how many calls are currently active for each buyer.

To get current in-progress calls, set created_at_start to today (or yesterday) and created_at_end to tomorrow.

GET https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=buyer&domain=calls&created_at_start=2026-04-22&created_at_end=2026-04-24

Swipe horizontally to view full table

Parameter	Value
api_key	[api_key]
company_id	1
domain	calls
facet	buyer
created_at_start	2026-04-22
created_at_end	2026-04-24

Note

facet=buyer is an alias for facet=target and only works for companies with the affiliate marketing feature enabled. If your company does not have that feature, use facet=target instead.

Warning

The Reports API response is cached and is not intended for realtime polling. For realtime call tracking, use webhooks to receive notifications when calls start, end, convert, and other call lifecycle events.

Tag Value Report

curl "https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28"

Swipe horizontally for full code

The above command returns JSON structured like this:

{
  "count": 3,
  "count_total": 3,
  "data": [
    {
      "id": "utm_campaign",
      "facet_name": "utm_campaign",
      "total_calls": 3,
      "repeat_count": 2.0,
      "duplicate_count": 0.0,
      "unique_calls": 1.0,
      "converted_count": 0.0,
      "revenue": 0.0,
      "payout": 0.0,
      "cost": 0.12,
      "total_duration": 3.666666666666667,
      "total_duration_percent": 0.4714045207910327,
      "rescued_count": 0.0,
      "rescued_revenue": 0.0,
      "connected_duration": 0.0,
      "connected_duration_percent": 0.0,
      "in_progress_count": 0.0,
      "profit": -0.12,
      "repeat_count_percent": 66.66666666666666,
      "duplicate_count_percent": 0,
      "converted_count_percent": 0,
      "rescued_count_percent": 0,
      "epc": 0,
      "cpc": 0
    }
  ]
}

Swipe horizontally for full code

Get a report for all calls between 2024-10-25 and 2024-10-28 faceted by tag_value name.

GET https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28

Swipe horizontally to view full table

Parameter	Value
api_key	[api_key]
company_id	1
domain	calls
facet	tag_value
created_at_start	2024-10-25
created_at_end	2024-10-28

Tag Value Name Report

curl "https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28&tag_value_key=utm_campaign"

Swipe horizontally for full code

The above command returns JSON structured like this:

{
  "count": 3,
  "count_total": 3,
  "data": [
    {
      "id": "ret_campaign_123",
      "facet_name": "ret_campaign_123",
      "total_calls": 2,
      "repeat_count": 2.0,
      "duplicate_count": 0.0,
      "unique_calls": 1.0,
      "converted_count": 0.0,
      "revenue": 0.0,
      "payout": 0.0,
      "cost": 0.12,
      "total_duration": 3.666666666666667,
      "total_duration_percent": 0.4714045207910327,
      "rescued_count": 0.0,
      "rescued_revenue": 0.0,
      "connected_duration": 0.0,
      "connected_duration_percent": 0.0,
      "in_progress_count": 0.0,
      "profit": -0.12,
      "repeat_count_percent": 66.66666666666666,
      "duplicate_count_percent": 0,
      "converted_count_percent": 0,
      "rescued_count_percent": 0,
      "epc": 0,
      "cpc": 0
    },
    {
      "id": "ret_campaign_456",
      "facet_name": "ret_campaign_456",
      "total_calls": 1,
      "repeat_count": 0,
      "duplicate_count": 0.0,
      "unique_calls": 1.0,
      "converted_count": 0.0,
      "revenue": 0.0,
      "payout": 0.0,
      "cost": 0.12,
      "total_duration": 3.666666666666667,
      "total_duration_percent": 0.4714045207910327,
      "rescued_count": 0.0,
      "rescued_revenue": 0.0,
      "connected_duration": 0.0,
      "connected_duration_percent": 0.0,
      "in_progress_count": 0.0,
      "profit": -0.12,
      "repeat_count_percent": 66.66666666666666,
      "duplicate_count_percent": 0,
      "converted_count_percent": 0,
      "rescued_count_percent": 0,
      "epc": 0,
      "cpc": 0
    }
  ]
}

Swipe horizontally for full code

Get a report for all calls between 2024-10-25 and 2024-10-28 faceted by the tag utm_campaign.

GET https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28&tag_value_key=utm_campaign

Swipe horizontally to view full table

Parameter	Value
api_key	[api_key]
company_id	1
domain	calls
facet	tag_value
created_at_start	2024-10-25
created_at_end	2024-10-28
tag_value_key	utm_campaign

Not all tag values are indexed

curl "https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28&tag_value_key=unindexed_tag_value"

Swipe horizontally for full code

The above command returns JSON structured like this:

{
  "count": 0,
  "count_total": 0,
  "data": []
}

Swipe horizontally for full code

To reduce the noise from billions of uninteresting values, we only report the values for Tags explicitly created for the company along with a few system Tags. To see a report on the values of unindexed_tag_value, please visit the Tags page and create a tag with key unindexed_tag_value. We will start indexing it from today. Let us know if you would like us to re-index past calls.

GET https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28&tag_value_key=unindexed_tag_value

Swipe horizontally to view full table

Parameter	Value
api_key	[api_key]
company_id	1
domain	calls
facet	tag_value
created_at_start	2024-10-25
created_at_end	2024-10-28
tag_value_key	unindexed_tag_value