# Monitor Task Ad Copy (Most Used)

## API Information

- **API Name**: Monitor Task Ad Copy (Most Used)
- **Request Method**: POST
- **API URL**: `open-api/v1/monitor/data`
- **Endpoint Path**: `/v3/api/ad-monitor-task/ad-copy-most-used`
- **Description**:
    - Get the most used ad copy list in the monitor task
    - Support sorting by usage count
    - Provide pagination query functionality
    - Analyze the usage frequency and effectiveness of ad copies
    - Usage Note: `Free`

**Request Headers:**

- Content-Type: application/json
- Accept: application/json

## Request Parameters

### Request Structure

| Parameter | Type   | Description                       | Example                                | Required | Default |
| --------- | ------ | --------------------------------- | -------------------------------------- | -------- | ------- |
| key       | string | User's external API request key   | "your_api_key_here"                   | Yes      |         |
| uri       | string | Endpoint path                     | "/v3/api/ad-monitor-task/ad-copy-most-used" | Yes      |         |
| params    | object | Request parameters object         | See parameter list                     | Yes      |         |

### Request Body Parameters (params object)

| Parameter | Type    | Required | Description                                                        |
|-----------|---------|----------|--------------------------------------------------------------------|
| task_id   | string  | true     | Task ID                                                            |
| order_by  | string  | false    | Sort field, values: ad_count(number of ads)<br/>last_discovered_at(latest ad date) |
| direction | string  | false    | Sort order, values: desc(descending)<br/>asc(ascending)          |
| page      | integer | false    | Page number (default 1)                                            |
| per_page  | integer | false    | Items per page (default 10)                                       |

### Request Example

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/ad-copy-most-used",
    "params": {
      "task_id": "68fa2e36789edb5700215e03",
      "direction": "desc",
      "page": 1,
      "per_page": 10
    }
  }'
```

## Response Parameters

### Response Structure

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

### Response Field Description

| Field Name | Type    | Description                     |
| ---------- | ------- | ------------------------------- |
| code       | Integer | Response status code, 200 means success |
| message    | String  | Response message                |
| data       | Object  | Response data                   |
| version    | String  | API version                     |
| timestamp  | String  | Response timestamp              |
| sign       | String  | Response signature              |
| remaining_credits | Long    | Current remaining available credits after this request |
| consumed_credits  | Long    | Credits consumed by this request                       |
| success    | Boolean | Request success status          |
| fail       | Boolean | Request failure status          |

### Response Data Information Fields

| Field Name              | Type              | Description                               |
|-------------------------|-------------------|-------------------------------------------|
| per_page                | integer           | Total items per page                      |
| total                    | integer           | Total data count                          |
| data                     | array [object]    | Data                                      |
| data[].ad_content        | string            | Copy content                              |
| data[].ad_count          | integer           | Number of ads using this copy             |
| data[].proportion        | integer           | Proportion (percentage)                   |
| data[].last_discovered_at| integer           | Latest usage date (timestamp in seconds)  |

## Response Example

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "per_page": 10,
    "total": 568,
    "data": [
      {
        "proportion": 2.59,
        "ad_count": 373,
        "last_discovered_at": 1758092400,
        "ad_content": "Dat scheelt een haartje."
      },
      {
        "proportion": 2.15,
        "ad_count": 309,
        "last_discovered_at": 1757314800,
        "ad_content": "Nu met flinke korting."
      },
      {
        "proportion": 1.83,
        "ad_count": 263,
        "last_discovered_at": 1757746800,
        "ad_content": "Je favoriete koffie gewoon thuis? Het is je verdiende boon."
      },
      {
        "proportion": 1.34,
        "ad_count": 193,
        "last_discovered_at": 1758006000,
        "ad_content": "Even bijtanken."
      },
      {
        "proportion": 1.27,
        "ad_count": 183,
        "last_discovered_at": 1756882800,
        "ad_content": "Op zoek naar een studielaptop? Helemaal jouw typen."
      },
      {
        "proportion": 1.25,
        "ad_count": 180,
        "last_discovered_at": 1758006000,
        "ad_content": "Bereik stap voor stap je sportdoelen."
      },
      {
        "proportion": 1.14,
        "ad_count": 164,
        "last_discovered_at": 1758006000,
        "ad_content": "Bestel 'm op Coolblue.nl of in onze app."
      },
      {
        "proportion": 1.11,
        "ad_count": 160,
        "last_discovered_at": 1757401200,
        "ad_content": "Die kun je in je zak steken."
      },
      {
        "proportion": 1.06,
        "ad_count": 152,
        "last_discovered_at": 1758006000,
        "ad_content": "Een schone vloer? Even wat stoom afblazen."
      },
      {
        "proportion": 0.98,
        "ad_count": 141,
        "last_discovered_at": 1758092400,
        "ad_content": "Creëer je eigen thuisbioscoop en geniet van kamervullend geluid."
      }
    ],
    "last_page": 57,
    "current_page": 1
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

## Error Codes

| Error Code | Description           |
| ---------- | --------------------- |
| 200        | Success               |
| 400        | Invalid request parameters |
| 500        | Internal server error |