Log inStart Free Trial
easyCoexistence Official APIs

Tagging people and adding a location to an Instagram post through the API

Instagram's API tags people with user_tags and adds a place with location_id, both set on the media container before it is published. user_tags lists public usernames, with x and y coordinates from 0.0 to 1.0 required on images; Meta describes it for images, videos and Stories. location_id takes the ID of a Page with location data, found through the Pages Search API.

easyCoexistence publishes photos, carousels, Reels and Stories with publish_instagram_post from Claude, ChatGPT or your own code.

0.0 to 1.0

Range of the x and y coordinates in user_tags, measured from the left and top edges of the image.

Images

Where user_tags requires x and y; they are optional on Stories and apply only to images and Stories.

Carousels

location_id is not supported on the images or videos inside a carousel, Meta's media reference says.

USER_TAGGING_FAILURE

The config_issue value when media publishes without its user tags, which Meta calls a partial success.

13 Mar 2018

When Meta opened tagging of locations and public Instagram users in API-published photos, to beta partners first.

How do you tag people in a post?

Add user_tags to the container. It is an array of objects, each with the username of a public Instagram account and, on an image, x and y: floats from 0.0 to 1.0 giving the tag's distance from the left and top edges. A location goes in location_id on the same call, and the container is then published with media_publish as usual.

An image container with a user tag and a location
POST /<IG_ID>/media
Content-Type: application/json

{
  "image_url": "https://example.com/team.jpg",
  "caption": "<CAPTION>",
  "user_tags": [
    { "username": "<USERNAME>", "x": 0.42, "y": 0.61 }
  ],
  "location_id": "<PAGE_ID>"
}

Which posts take user tags and a location?

Meta's media reference describes user_tags for images, videos and Stories, with x and y applying only to images and Stories, and lists the parameters each container takes. On a carousel, the location goes on the carousel container, since location_id is not supported on the images or videos inside it:

Imageuser_tags with x and y, and location_id
Reeluser_tags by username, and location_id
Storyuser_tags, with x and y optional; no location_id in its syntax
Carousel containerlocation_id, and no user_tags in its syntax
Carousel itemsNo location_id

How do you find a location_id?

Search for a Page. location_id is the ID of a Page associated with a location, and Meta's reference points to the Pages Search API, GET /pages/search with q and fields=id,name,location, then to checking that the chosen Page has location data. A Page without it fails with INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID. The search runs on Meta's Graph API with your own Meta app's token: a user token, or for public Page information an app token with the Page Public Metadata Access feature.

Searching for a Page with a location
GET /pages/search
  ?q=<PLACE_NAME>
  &fields=id,name,location
  &access_token=<ACCESS_TOKEN>

What happens if a tag does not attach?

The post can still go live. media_publish then returns config_issue set to USER_TAGGING_FAILURE, meaning the media published without its user tags. Meta calls this a partial success and asks apps to treat it as a signal to reconcile rather than an error, since the media ID is valid; publishing again would create a second post.

Do user tags work with Instagram Login?

Meta's media reference lists user_tags and location_id for container creation without tying them to one login. Its page for the Instagram API with Instagram Login, though, says that setup cannot access ads or tagging, without saying which tagging it means. Before building on either parameter with Instagram Login, publish a test post and check the response and the post itself.

How do you tag people through easyCoexistence?

You cannot yet. publish_instagram_post creates the container itself and takes no user_tags or location_id, and Instagram tokens are not handed out for a call of your own. Publish the post with publish_instagram_post, then add the tags and the location in the Instagram app, from the post's Edit option.

Common mistakes

  • Leaving x and y off an image tag. Meta requires them on images; only Stories make them optional.
  • Giving coordinates in pixels or percent. x and y are floats from 0.0 to 1.0, measured from the left and top edges.
  • Setting location_id on carousel items. Meta does not support it on the images or videos inside a carousel.
  • Tagging a private account. user_tags takes the usernames of public Instagram accounts.
Doing this with EasyCoexistence

The tool takes no user_tags or location_id, so people and places are tagged in the Instagram app, from the post's Edit option. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

Can I tag a private Instagram account through the API?

No. Meta's media reference says user_tags takes the usernames of public Instagram accounts, so a private account cannot be tagged this way.

How many people can be tagged in one post?

Meta's reference for user_tags gives no maximum. The limit of 20 it states is for @ tags in a caption.

Can I add a location to a Story through the API?

No. Meta's syntax for a Story container lists user_tags but not location_id.

Can I tag a product instead of a person?

Product tags are a separate feature, which Meta's overview lists as supported with Facebook Login and Unified Login, not with Instagram Login.

Keep reading

Connect your first channel in two minutes.

No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.

  • 3 days free
  • Cancel any time
  • Official APIs only
  • Monitored 24/7

Verified on