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

# Instagram Settings

> API settings for posting to Instagram

## Settings Schema

When creating a post for Instagram, use the following settings schema:

```json theme={null}
{
  "settings": {
    "__type": "instagram",
    "post_type": "post",
    "is_trial_reel": false,
    "collaborators": [],
    "audio": {
      "id": "587784541076604",
      "audio_volume": 100,
      "video_volume": 100
    }
  }
}
```

<Note>
  Use `__type: "instagram"` for Facebook Business-linked accounts and `__type: "instagram-standalone"` for standalone Instagram accounts. Both use the same settings schema, except `audio`, which is only available for Facebook Business-linked accounts.
</Note>

## Fields

| Field                 | Type      | Required | Description                                   |
| --------------------- | --------- | -------- | --------------------------------------------- |
| `__type`              | `string`  | Yes      | `instagram` or `instagram-standalone`         |
| `post_type`           | `string`  | Yes      | Type of Instagram post                        |
| `is_trial_reel`       | `boolean` | No       | Whether to post as a trial reel               |
| `graduation_strategy` | `string`  | No       | Graduation strategy for trial reels           |
| `collaborators`       | `array`   | No       | List of collaborator usernames                |
| `audio`               | `object`  | No       | Audio to attach to a Reel (single video only) |

### `post_type`

| Value   | Description                          |
| ------- | ------------------------------------ |
| `post`  | Regular feed post                    |
| `story` | Instagram Story (24-hour visibility) |

### `is_trial_reel`

When set to `true`, the post will be published as a trial reel with limited initial visibility.

### `graduation_strategy`

Controls how trial reels graduate to full visibility. Only applicable when `is_trial_reel` is `true`.

| Value            | Description                                 |
| ---------------- | ------------------------------------------- |
| `MANUAL`         | Manually graduate the reel                  |
| `SS_PERFORMANCE` | Automatically graduate based on performance |

### `collaborators`

Array of collaborator objects. Each collaborator will receive an invite to be added as a collaborator on the post.

```json theme={null}
{
  "collaborators": [
    { "label": "username1" },
    { "label": "username2" }
  ]
}
```

### `audio`

Attach music or an original sound to a Reel, based on the
[Instagram Audio API](https://developers.facebook.com/docs/instagram-platform/content-publishing/audio-api/).

<Warning>
  Audio can only be attached to a Reel — a single video with `post_type: "post"`.
  It is not supported on Stories, carousels, image posts, or on
  `instagram-standalone` channels (the Audio API requires Facebook Login).
</Warning>

| Field          | Type     | Required | Description                                                   |
| -------------- | -------- | -------- | ------------------------------------------------------------- |
| `id`           | `string` | Yes      | The audio asset ID                                            |
| `title`        | `string` | No       | Audio title (display only)                                    |
| `artist`       | `string` | No       | Artist or creator name (display only)                         |
| `image`        | `string` | No       | Cover artwork URL (display only)                              |
| `audio_volume` | `number` | No       | Volume of the attached audio, `0`-`100` (default `100`)       |
| `video_volume` | `number` | No       | Volume of the original video audio, `0`-`100` (default `100`) |

To find audio IDs, use the [trigger endpoint](/public-api/integrations/trigger)
with the `audioSearch` tool:

```bash theme={null}
curl -X POST https://api.groniz.com/public/v1/integration-trigger/{integrationId} \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"methodName": "audioSearch", "data": {"q": "summer vibes", "type": "music"}}'
```

| Parameter | Description                                                                              |
| --------- | ---------------------------------------------------------------------------------------- |
| `q`       | Search query — leave empty to get trending audio                                         |
| `type`    | `music` (royalty-free catalog) or `original_sound` (user-generated), defaults to `music` |

The response contains `{ output: [{ id, title, artist, image, duration, previewUrl }] }` —
pass the chosen `id` into `settings.audio.id`.

<Note>
  Only audio authorized for third-party use is returned, so the catalog can be
  smaller than what you see in the Instagram app.
</Note>

***

## Complete Example

### Feed Post

```json theme={null}
{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "Beautiful sunset today! 🌅\n\n#sunset #photography #nature",
          "image": [
            {
              "id": "image-id",
              "path": "https://api.groniz.com/sunset.jpg"
            }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "post",
        "is_trial_reel": false,
        "collaborators": []
      }
    }
  ]
}
```

### Story Post

```json theme={null}
{
  "type": "now",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "",
          "image": [
            {
              "id": "story-image-id",
              "path": "https://api.groniz.com/story.jpg"
            }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "story"
      }
    }
  ]
}
```

### Collaborative Post

```json theme={null}
{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "Amazing collab with @partner! 🤝",
          "image": [
            {
              "id": "collab-image-id",
              "path": "https://api.groniz.com/collab.jpg"
            }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "post",
        "collaborators": [
          { "label": "partner_username" }
        ]
      }
    }
  ]
}
```

### Reel with Audio

Attach audio found with `audioSearch` to a single-video Reel:

```json theme={null}
{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "New reel with trending audio! 🎵",
          "image": [
            {
              "id": "video-id",
              "path": "https://api.groniz.com/reel.mp4"
            }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "post",
        "audio": {
          "id": "587784541076604",
          "audio_volume": 80,
          "video_volume": 20
        }
      }
    }
  ]
}
```

### Carousel Post

Create a carousel by adding multiple images:

```json theme={null}
{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "Swipe to see all the photos! 📸",
          "image": [
            { "id": "img1", "path": "https://api.groniz.com/1.jpg" },
            { "id": "img2", "path": "https://api.groniz.com/2.jpg" },
            { "id": "img3", "path": "https://api.groniz.com/3.jpg" }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "post"
      }
    }
  ]
}
```