# GTR Socials API

> Use the GTR Socials API to place orders, check status, and manage your account balance.

- **HTML docs:** https://gtrsocials.com/api
- **Markdown (AI-friendly):** https://gtrsocials.com/api.md
- **MCP server:** https://gtrsocials.com/mcp
- **API URL:** `https://gtrsocials.com/api/v2`
- **HTTP method:** `POST`
- **Response format:** JSON
- **Example PHP client:** https://gtrsocials.com/example.txt

## Authentication

Get your API key from [Account Settings](https://gtrsocials.com/settings).

Send every request as `POST` form fields (or JSON body) to `https://gtrsocials.com/api/v2` with:

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | API action name (see below) |

Add funds to your balance before placing orders. Use the service ID from the service list — not a provider ID.

## Action: services

List available services.

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `services` |

### Example response

```json
[
    {
        "service": 1,
        "name": "Followers",
        "type": "Default",
        "category": "Instagram",
        "rate": "0.9000",
        "min": "50",
        "max": "10000",
        "refill": true,
        "cancel": true
    },
    {
        "service": 2,
        "name": "Comments",
        "type": "Custom Comments",
        "category": "Instagram",
        "rate": "8.0000",
        "min": "10",
        "max": "1500",
        "refill": false,
        "cancel": true
    }
]
```

`rate` is the price per 1000 units. The `type` field shows which extra parameters are required when placing an order.

## Action: add

Place a default order (link + quantity). Other service types may require additional fields — check `type` from the service list (e.g. `comments`, `keywords`, `username`, `answer_number`).

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `add` |
| `service` | Service ID |
| `link` | Link to page |
| `quantity` | Needed quantity |
| `runs` | Optional. Runs to deliver (drip-feed) |
| `interval` | Optional. Interval in minutes (drip-feed) |

### Example response

```json
{
    "order": 23501
}
```

## Action: status (single order)

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `status` |
| `order` | Order ID returned by the add action |

### Example response

```json
{
    "charge": "0.27819",
    "start_count": "3572",
    "status": "Partial",
    "remains": "157",
    "currency": "USD"
}
```

## Action: status (multiple orders)

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `status` |
| `orders` | Order IDs separated by a comma (up to 100 IDs) |

### Example response

```json
{
    "1": {
        "charge": "0.27819",
        "start_count": "3572",
        "status": "Partial",
        "remains": "157",
        "currency": "USD"
    },
    "10": {
        "error": "Incorrect order ID"
    },
    "100": {
        "charge": "1.44219",
        "start_count": "234",
        "status": "In progress",
        "remains": "10",
        "currency": "USD"
    }
}
```

## Action: refill (single)

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `refill` |
| `order` | Order ID |

### Example response

```json
{
    "refill": "1"
}
```

## Action: refill (multiple)

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `refill` |
| `orders` | Order IDs separated by a comma (up to 100 IDs) |

### Example response

```json
[
    {
        "order": 1,
        "refill": 1
    },
    {
        "order": 2,
        "refill": 2
    },
    {
        "order": 3,
        "refill": {
            "error": "Incorrect order ID"
        }
    }
]
```

## Action: refill_status (single)

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `refill_status` |
| `refill` | Refill ID |

### Example response

```json
{
    "status": "Completed"
}
```

Refill status lookup is not fully tracked yet. Unknown refill IDs return `{"error": "Refill not found"}`.

## Action: refill_status (multiple)

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `refill_status` |
| `refills` | Refill IDs separated by a comma (up to 100 IDs) |

### Example response

```json
[
    {
        "refill": 1,
        "status": "Completed"
    },
    {
        "refill": 2,
        "status": "Rejected"
    },
    {
        "refill": 3,
        "status": {
            "error": "Refill not found"
        }
    }
]
```

## Action: cancel

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `cancel` |
| `orders` | Order IDs separated by a comma (up to 100 IDs) |

### Example response

```json
[
    {
        "order": 9,
        "cancel": {
            "error": "Incorrect order ID"
        }
    },
    {
        "order": 2,
        "cancel": 1
    }
]
```

## Action: balance

| Parameter | Description |
| --- | --- |
| `key` | Your API key |
| `action` | `balance` |

### Example response

```json
{
    "balance": "100.8429",
    "currency": "USD"
}
```