> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postqueen.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Instagram Settings
> API settings for posting to Instagram
Instagram posts use one settings block. `post_type` chooses a feed post or a Story. Collaborators, trial reels and Reel audio are optional additions on top.
Creating the OAuth app and connecting a channel: [Instagram setup guide](/installation/providers/instagram).
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.
## Settings Schema
```json theme={"system"}
{
"settings": {
"__type": "instagram",
"post_type": "post",
"is_trial_reel": false,
"collaborators": [],
"audio": {
"id": "587784541076604",
"audio_volume": 100,
"video_volume": 100
}
}
}
```
## 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={"system"}
{
"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/).
Audio can only be attached to a Reel, which is a single video with `post_type: "post"`.
It is not supported on Stories, carousels or image posts, and not on
`instagram-standalone` channels (the Audio API requires Facebook Login).
| 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`) |
#### Finding an audio ID
Use the [trigger endpoint](/public-api/integrations/trigger) with the `audioSearch` tool:
```bash theme={"system"}
curl -X POST https://api.postqueen.ai/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 }] }`.
You now have an audio ID. Pass the chosen `id` into `settings.audio.id`.
Only audio authorized for third-party use is returned, so the catalog can be
smaller than what you see in the Instagram app.
***
## Complete Example
```json theme={"system"}
{
"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://uploads.postqueen.ai/sunset.jpg"
}
]
}
],
"settings": {
"__type": "instagram",
"post_type": "post",
"is_trial_reel": false,
"collaborators": []
}
}
]
}
```
```json theme={"system"}
{
"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://uploads.postqueen.ai/story.jpg"
}
]
}
],
"settings": {
"__type": "instagram",
"post_type": "story"
}
}
]
}
```
```json theme={"system"}
{
"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://uploads.postqueen.ai/collab.jpg"
}
]
}
],
"settings": {
"__type": "instagram",
"post_type": "post",
"collaborators": [
{ "label": "partner_username" }
]
}
}
]
}
```
Attach audio found with `audioSearch` to a single-video Reel:
```json theme={"system"}
{
"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://uploads.postqueen.ai/reel.mp4"
}
]
}
],
"settings": {
"__type": "instagram",
"post_type": "post",
"audio": {
"id": "587784541076604",
"audio_volume": 80,
"video_volume": 20
}
}
}
]
}
```
Create a carousel by adding multiple images:
```json theme={"system"}
{
"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://uploads.postqueen.ai/1.jpg" },
{ "id": "img2", "path": "https://uploads.postqueen.ai/2.jpg" },
{ "id": "img3", "path": "https://uploads.postqueen.ai/3.jpg" }
]
}
],
"settings": {
"__type": "instagram",
"post_type": "post"
}
}
]
}
```
## Next steps
Create the OAuth app and link the Instagram account.
The settings for channels connected without Facebook Business.
The trigger endpoint behind `audioSearch` and the other provider tools.
The create endpoint, field by field, with a worked request.