> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Particle: Get Advertising Timeseries

> Get time-bucketed podcast ad counts, host-read vs pre-recorded, for one sponsor_id or one company_id (exactly one is required).

Get time-bucketed podcast ad counts, host-read vs pre-recorded, for one sponsor\_id or one company\_id (exactly one is required).

> [!NOTE]
>
> Tool ID: `particle_get_advertising_timeseries`

## Run this action

This action has conditional or dynamic inputs. A static example cannot describe these inputs reliably.

Read the live contract before you execute this action:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline describe particle_get_advertising_timeseries --json
```

## Example response

The SDK returns this shape at `result.toolResponse.raw`. The example values illustrate the response.

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "data": {
    "buckets": [
      {
        "count": 123,
        "host_read_count": 123,
        "pre_recorded_count": 123,
        "start": "example"
      }
    ],
    "distinct_episodes": 123,
    "distinct_podcasts": 123,
    "host_read_count": 123,
    "interval": "day",
    "pre_recorded_count": 123,
    "total_ads": 123
  }
}
```

Use `deepline describe particle_get_advertising_timeseries --json` for the latest machine-readable contract.

## Input reference

Returns time-bucketed ad placement counts for a sponsor or company, split into host-read and pre-recorded placements, plus range totals. Exactly one of sponsor\_id or company\_id is required. company\_id aggregates across every sponsor alias linked to the company. Pass podcast\_id or publisher\_id to scope the counts to one show or network, matching the mentions timeseries so both series can be charted under the same scope. Counts use the same attribution as the sponsor podcasts and segments endpoints, so bucket sums agree with their ad\_count values. Network promos are excluded.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.sponsor_id` | `string` | No | — | Sponsor ID. Exactly one of sponsor\_id or company\_id is required. |
| `payload.company_id` | `string` | No | — | Company ID, domain, or entity slug. Aggregates across every sponsor alias linked to the company. |
| `payload.podcast_id` | `string` | No | — | Restrict to ad placements on one podcast, by slug or ID. |
| `payload.publisher_id` | `string` | No | — | Restrict to ad placements on podcasts attributed to one publisher (network), by slug or ID. |
| `payload.since` | `string` | No | — | Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time. |
| `payload.until` | `string` | No | — | End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now. |
| `payload.published_after` | `string` | No | — | Deprecated alias of since. |
| `payload.published_before` | `string` | No | — | Deprecated alias of until. |
| `payload.interval` | `"day" \| "week" \| "month"` | No | `"week"` | Bucket width. Weeks start on Monday and all buckets are UTC-aligned. Allowed: `day`, `week`, `month`. |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Returns time-bucketed ad placement counts for a sponsor or company, split into host-read and pre-recorded placements, plus range totals. Exactly one of sponsor_id or company_id is required; company_id aggregates across every sponsor alias linked to the company. Pass podcast_id or publisher_id to scope the counts to one show or network, matching the mentions timeseries so both series can be charted under the same scope. Counts use the same attribution as the sponsor podcasts and segments endpoints, so bucket sums agree with their ad_count values. Network promos are excluded.",
    "properties": {
      "sponsor_id": {
        "type": "string",
        "description": "Sponsor ID. Exactly one of sponsor_id or company_id is required."
      },
      "company_id": {
        "type": "string",
        "description": "Company ID, domain, or entity slug. Aggregates across every sponsor alias linked to the company."
      },
      "podcast_id": {
        "type": "string",
        "description": "Restrict to ad placements on one podcast, by slug or ID."
      },
      "publisher_id": {
        "type": "string",
        "description": "Restrict to ad placements on podcasts attributed to one publisher (network), by slug or ID."
      },
      "since": {
        "type": "string",
        "description": "Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time."
      },
      "until": {
        "type": "string",
        "description": "End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now."
      },
      "published_after": {
        "type": "string",
        "description": "Deprecated alias of since."
      },
      "published_before": {
        "type": "string",
        "description": "Deprecated alias of until."
      },
      "interval": {
        "type": "string",
        "description": "Bucket width. Weeks start on Monday and all buckets are UTC-aligned.",
        "default": "week",
        "enum": [
          "day",
          "week",
          "month"
        ]
      }
    },
    "required": [],
    "oneOf": [
      {
        "required": [
          "sponsor_id"
        ]
      },
      {
        "required": [
          "company_id"
        ]
      }
    ],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

Standard tool result payload.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `object` | Yes | — | Provider response payload. |
| `result.data.buckets` | `array \| null` | Yes | — | Contiguous zero-filled buckets in ascending order |
| `result.data.buckets[].count` | `integer` | Yes | — | Ad placements in this bucket Format: `int64`. |
| `result.data.buckets[].host_read_count` | `integer` | Yes | — | Host-read placements in this bucket Format: `int64`. |
| `result.data.buckets[].pre_recorded_count` | `integer` | Yes | — | Placements not read by the host in this bucket Format: `int64`. |
| `result.data.buckets[].start` | `string` | Yes | — | Bucket start as a UTC date |
| `result.data.distinct_episodes` | `integer` | Yes | — | Distinct episodes those placements aired in Format: `int64`. |
| `result.data.distinct_podcasts` | `integer` | Yes | — | Distinct podcasts those placements aired on Format: `int64`. |
| `result.data.end` | `string` | No | — | UTC date of the range's exclusive upper bound. When the bound falls inside a day, such as the default of now, ads on this date up to the bound are still counted. |
| `result.data.host_read_count` | `integer` | Yes | — | Host-read placements in the range Format: `int64`. |
| `result.data.interval` | `"day" \| "week" \| "month"` | Yes | — | Bucket width Allowed: `day`, `week`, `month`. |
| `result.data.pre_recorded_count` | `integer` | Yes | — | Placements not read by the host in the range Format: `int64`. |
| `result.data.start` | `string` | No | — | Start of the first bucket as a UTC date |
| `result.data.total_ads` | `integer` | Yes | — | Ad placements matching the filters in the range Format: `int64`. |
| `result.meta` | `object` | No | — | Additional response metadata (status, paging). |

<details>
  <summary>Show raw output schema</summary>

  ### Output JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Standard tool result payload.",
    "properties": {
      "data": {
        "type": "object",
        "description": "Provider response payload.",
        "properties": {
          "buckets": {
            "type": [
              "array",
              "null"
            ],
            "description": "Contiguous zero-filled buckets in ascending order",
            "items": {
              "type": "object",
              "properties": {
                "count": {
                  "type": "integer",
                  "description": "Ad placements in this bucket",
                  "format": "int64"
                },
                "host_read_count": {
                  "type": "integer",
                  "description": "Host-read placements in this bucket",
                  "format": "int64"
                },
                "pre_recorded_count": {
                  "type": "integer",
                  "description": "Placements not read by the host in this bucket",
                  "format": "int64"
                },
                "start": {
                  "type": "string",
                  "description": "Bucket start as a UTC date"
                }
              },
              "required": [
                "start",
                "count",
                "host_read_count",
                "pre_recorded_count"
              ],
              "additionalProperties": false
            }
          },
          "distinct_episodes": {
            "type": "integer",
            "description": "Distinct episodes those placements aired in",
            "format": "int64"
          },
          "distinct_podcasts": {
            "type": "integer",
            "description": "Distinct podcasts those placements aired on",
            "format": "int64"
          },
          "end": {
            "type": "string",
            "description": "UTC date of the range's exclusive upper bound. When the bound falls inside a day, such as the default of now, ads on this date up to the bound are still counted."
          },
          "host_read_count": {
            "type": "integer",
            "description": "Host-read placements in the range",
            "format": "int64"
          },
          "interval": {
            "type": "string",
            "description": "Bucket width",
            "enum": [
              "day",
              "week",
              "month"
            ]
          },
          "pre_recorded_count": {
            "type": "integer",
            "description": "Placements not read by the host in the range",
            "format": "int64"
          },
          "start": {
            "type": "string",
            "description": "Start of the first bucket as a UTC date"
          },
          "total_ads": {
            "type": "integer",
            "description": "Ad placements matching the filters in the range",
            "format": "int64"
          }
        },
        "required": [
          "interval",
          "total_ads",
          "host_read_count",
          "pre_recorded_count",
          "distinct_episodes",
          "distinct_podcasts",
          "buckets"
        ],
        "additionalProperties": false
      },
      "meta": {
        "type": "object",
        "description": "Additional response metadata (status, paging).",
        "additionalProperties": true
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.

## Related documentation

* [Particle provider guide](https://deepline.com/docs/providers/particle/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.