Skip to main content

Agorapulse's Open API explained

What actions can be taken with the Open API

With Agorapulse's Open API, you can integrate your social media reporting data into external systems, create new calendar notes or drafts, and sync information on new inbox items to external tools. This allows for improved decision-making, visibility, and saving time by automating data retrieval.

For more information on how to generate an API key and how to retrieve Organization ID, Workspace ID, and Profile UIDs, take a look at this article.


In this article, we will cover:

Note: Open API is available to users on a Custom subscription plan. If you would like to change your plan to access this feature, feel free to reach out to us here.

How to navigate the API reference document

The left-hand navigation of the API reference groups every endpoint into the following categories:

  • Account & Workspaces: Organizations, Workspaces, Profiles, and Groups

  • Publishing: Drafts, Calendar notes, and Pinterest boards

  • Content Library: Media

  • Inbox & Engagement: Conversations, Items, and Replies

  • Social Listening: Searches, Metrics, and Mentions

  • Analytics & Reporting: Reports and Competitors

Each endpoint page shows its path parameters, query parameters, request body, and example responses. Test Request can be used to send a live call using the API key in the Value field and returns the real response from your account.

To work with the specification in your own tooling, click Download OpenAPI Document at the top of the page.


What is available with the Open API?

The Open API can be used to manage publishing, social inbox conversations, social listening, and analytics. In the drop-downs below, we will cover what actions can be performed in each section

Publishing

The Publishing section of the Open API allows you to search, create, edit, and delete Calendar Notes, as well as retrieve a list of the boards that are available on a Pinterest profile.

Calendar Notes

  • Search calendar notes: Search and filter calendar notes in the specified workspace

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

    • (Optional) Query Parameters

      • Since: Filters notes after the date

      • Until: Filters notes before this date
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • profileUids: Filters by profile unique identifiers
        ​

  • Create a new calendar note: Creates a new calendar note with the specified content

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • Request Body (Updated calendar note data)

      • Color (Color of the calendar note). The available calendar note colors are:

        • BLUE

        • RED

        • YELLOW

        • GREEN

        • PURPLE

        • PINK

        • ORANGE

        • MINT

        • CYAN

        • GREY

      • endDate (Note end date)

      • startDate (Note start date)
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • title (Note title)

      • (Optional) body (Content of the note)

      • (Optional) profileUids (List of profile unique identifiers associated with the note)
        ​

  • Update a calendar note: Updates an existing calendar note with new data

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • uid (Calendar note unique identifier)

      • Body (Updated calendar note data)

      • Color (Color of the calendar note). The available calendar note colors are:

        • BLUE

        • RED

        • YELLOW

        • GREEN

        • PURPLE

        • PINK

        • ORANGE

        • MINT

        • CYAN

        • GREY

      • endDate (Note end date)

      • startDate (Note start date)
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • title (Note title)

      • (Optional) body (Content of the note)

      • (Optional) profileUids (List of profile unique identifiers associated with the note)
        ​

  • Delete a calendar note: Deletes a calendar note (Deletes a calendar note by its UID)

    • Required parameters:

      • organizationId (Organization identifier)

      • workspaceId (Workspace identifier)

      • profileUid (Calendar note unique identifier).

Pinterest boards

  • List a Pinterest profile's boards: Lists the boards a Pinterest profile can publish to

    • Required parameters:

      • organizationId (Organization identifier)

      • workspaceId (Workspace identifier)

      • profileUid (Pinterest profile identifier, as returned by the profiles endpoint).

​

Content Library

The Content Library section of the Open API lets you create a media upload slot so you can upload media to the Content Library and for you to get the status of an uploaded media item.

Media

  • Create a media upload slot: Generates a presigned upload URL and registers a media item awaiting upload.

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • Body (Media to create)

      • fileName (File name with extension, e.g. clip.mp4).
        ​

  • Get media status: Returns the current status and, once probed, the technical metadata of the uploaded media

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • mediaUid (Media identifier).

Inbox & Engagement

The Inbox section of the Open API makes it so you can retrieve and reply to inbox items.

Conversations

  • Get conversation messages: Read conversation threads from your social inbox.

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • profileUid (Profile identifier)

      • conversationId (Conversation identifier)

    • (Optional) Query Parameters:

      • since: Filters notes after the date

      • until: Filters notes before this date
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • offset: Offset for pagination

      • limit: Maximum number of messages to return per page. Must be between 1 and 25

      • order: Sort order for the results. ASC for ascending (oldest first), DESC for descending (newest first).

Items

  • Find items: Find inbox items (comments, messages, reviews)

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

    • (Optional) Query Parameters:

      • profilUids: Set of profile unique identifiers to filter items; at least one is required. Only items from these profiles will be returned.

      • toReview: Filter items that need review (not yet approved by a manager)

      • labels: Filter items by labels. Only items with these labels will be returned

      • sentiments: Filter items by sentiment (positive, negative, neutral)

      • types: Filter items by type. Specify the types of items to retrieve:

        • ADS_COMMNENT

        • ORGANIC_COMMENT

        • MENTION

        • RATING

        • REEL_COMMENT

        • STORY_MENTION_CONVERSATION

        • PROFILE_COMMENT

        • PROFILE_MESSAGE

        • profileComment and profileMessage: Returns what the profile itself replied with. Every other value returns incoming items

      • parentIds: Filter items by parent, taking the identifier of an item returned by this endpoint. Returns the children of these items: the comments of a post, the replies of a comment, the messages of a conversation

      • since: Filters notes after the date

      • until: Filters notes before this date
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • offset: Offset for pagination

      • limit: Maximum number of messages to return per page. Must be between 1 and 25

      • order: Sort order for the results. ASC for ascending (oldest first), DESC for descending (newest first).
        ​

  • Get item: Retrieves an inbox item (comments, messages, reviews)

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • profileUid (Profile identifier)

      • itemID (Item identifier, as returned by the items endpoint)

Replies

  • Reply to an item: Reply to an inbox item

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • profileUid (Profile identifier)

      • Request Body (Request to create a reply to an inbox item)

      • itemId (The Identifier of the inbox item to reply to)

      • message (The content of the reply message)

      • (Optional) excludedUsers: List of user IDs to exclude from mentions (Twitter-specific)

      • (Optional) privateReply: When true, sends a private message to the user instead of replying publicly to a public item (e.g., comment). The reply will be sent as a direct/private message. Supported by Facebook, Instagram, and X (Twitter) only.

Social Listening

The Social Listening section of the Open API allows you to view a list of active searches, view metrics from active searches (engagement, keywords, sentiment, & volume), and find items that the listening search has matched.

Searches

  • List searches: Lists the listening searches of a workspace, with the networks they cover, their competitors when they are competitive, and their metrics for the last seven days

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

Metrics

  • Get the search engagement: Sums the reactions, comments, and shares the items a listening search matched collected over the requested window, as plain totals or broken down along one dimension. Views are not counted.

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • searchID (The listening search identifier)

    • (Optional) Query Parameters:

      • since: Filters notes after the date
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • until: Filters notes before this date

      • networks: Take into account the items from these social networks only:

        • FACEBOOK

        • INSTAGRAM

        • TWITTER

        • LINKEDIN

        • TIKTOK

        • YOUTUBE

        • REDDIT

        • WEB_NEWS

        • WEB_BLOG

        • WEB_FORUM

      • sentiments: Take into account the items with these sentiments only:

        • POSITIVE

        • NEGATIVE

        • NEUTRAL

      • keyword: Take into account the items whose extracted keywords include this one only, matched exactly and case-insensitively against the values the keywords endpoint returns. An unknown keyword returns an empty result

      • competitors: Take into account only the items that matched these competitors; competitive search only. The names are the ones the searches endpoint returns; an unknown name, or a search that is not competitive, is rejected. An item matching two competitors is counted for both

      • groupBy: Omit it for the overall figure.

        • DATE: Returns one group per period step and echoes the granularity

        • NETWORK: One per social network,

        • COMPETITOR: One per competitor of a competitive search
          ​

  • Get the search keywords: Lists the topics a listening search is talked about over the requested window, each with the number of items mentioning it, how they were classified, and the interactions they collected.

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • searchID (The listening search identifier)

    • (Optional) Query Parameters:

      • since: Filters notes after the date
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • until: Filters notes before this date

      • networks: Take into account the items from these social networks only:

        • FACEBOOK

        • INSTAGRAM

        • TWITTER

        • LINKEDIN

        • TIKTOK

        • YOUTUBE

        • REDDIT

        • WEB_NEWS

        • WEB_BLOG

        • WEB_FORUM

      • sentiments: Take into account the items with these sentiments only:

        • POSITIVE

        • NEGATIVE

        • NEUTRAL

      • keyword: Take into account the items whose extracted keywords include this one only, matched exactly and case-insensitively against the values the keywords endpoint returns. An unknown keyword returns an empty result

      • competitors: Take into account only the items that matched these competitors; competitive search only. The names are the ones the searches endpoint returns; an unknown name, or a search that is not competitive, is rejected. An item matching two competitors is counted for both

      • size: The number of keywords to return. Must be between 1 and 100
        ​

  • Get the search sentiment: Classifies the items a listening search matched as positive, neutral, or negative over the requested window.

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • searchID (The listening search identifier)

    • (Optional) Query Parameters:

      • since: Filters notes after the date
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • until: Filters notes before this date

      • networks: Take into account the items from these social networks only:

        • FACEBOOK

        • INSTAGRAM

        • TWITTER

        • LINKEDIN

        • TIKTOK

        • YOUTUBE

        • REDDIT

        • WEB_NEWS

        • WEB_BLOG

        • WEB_FORUM

      • sentiments: Take into account the items with these sentiments only:

        • POSITIVE

        • NEGATIVE

        • NEUTRAL

      • keyword: Take into account the items whose extracted keywords include this one only, matched exactly and case-insensitively against the values the keywords endpoint returns. An unknown keyword returns an empty result

      • competitors: Take into account only the items that matched these competitors; competitive search only. The names are the ones the searches endpoint returns; an unknown name, or a search that is not competitive, is rejected. An item matching two competitors is counted for both

      • groupBy: Omit it for the overall figure.

        • DATE: Returns one group per period step and echoes the granularity

        • NETWORK: One per social network,

        • COMPETITOR: One per competitor of a competitive search
          ​

  • Get the search volume: Counts the items a listening search matched over the requested window

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • searchID (The listening search identifier)

    • (Optional) Query Parameters:

      • since: Filters notes after the date
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • until: Filters notes before this date

      • networks: Take into account the items from these social networks only:

        • FACEBOOK

        • INSTAGRAM

        • TWITTER

        • LINKEDIN

        • TIKTOK

        • YOUTUBE

        • REDDIT

        • WEB_NEWS

        • WEB_BLOG

        • WEB_FORUM

      • sentiments: Take into account the items with these sentiments only:

        • POSITIVE

        • NEGATIVE

        • NEUTRAL

      • keyword: Take into account the items whose extracted keywords include this one only, matched exactly and case-insensitively against the values the keywords endpoint returns. An unknown keyword returns an empty result

      • competitors: Take into account only the items that matched these competitors; competitive search only. The names are the ones the searches endpoint returns; an unknown name, or a search that is not competitive, is rejected. An item matching two competitors is counted for both

      • groupBy: Omit it for the overall figure.

        • DATE: Returns one group per period step and echoes the granularity

        • NETWORK: One per social network,

        • COMPETITOR: One per competitor of a competitive search

Mentions

  • Find items: Lists the items a listening search matched, with optional filters on the publication date, the social network, and the sentiment.

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceId (Workspace identifier)

      • searchID (The listening search identifier)

    • (Optional) Query Parameters:

      • since: Filters notes after the date
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • until: Filters notes before this date

      • networks: Take into account the items from these social networks only:

        • FACEBOOK

        • INSTAGRAM

        • TWITTER

        • LINKEDIN

        • TIKTOK

        • YOUTUBE

        • REDDIT

        • WEB_NEWS

        • WEB_BLOG

        • WEB_FORUM

      • sentiments: Take into account the items with these sentiments only:

        • POSITIVE

        • NEGATIVE

        • NEUTRAL

      • keyword: Take into account the items whose extracted keywords include this one only, matched exactly and case-insensitively against the values the keywords endpoint returns. An unknown keyword returns an empty result

      • competitors: Take into account only the items that matched these competitors; competitive search only. The names are the ones the searches endpoint returns; an unknown name, or a search that is not competitive, is rejected. An item matching two competitors is counted for both

      • offset: Offset returned by the previous response, to read the next page

      • limit: Maximum number of items to return per page. Must be between 1 and 25.

      • orderBy: Field the items are sorted on.

        • DATE: For the publication date

        • ENGAGEMENT: For the interactions the item collected.

Analytics & Reporting

The Report section of the Open API allows you to retrieve Audience, Content, Community Management, and Competitor reporting data.

Reports

The Analytics Open API is supported for the following social networks:

  • Facebook

  • Instagram

  • LinkedIn

  • TikTok

  • YouTube

Note: Due to terms of service restrictions, X (Twitter) is not supported by the Analytics Open API.

The Analytics Open API provides access to the same data available via CSV exports from Agorapulse reports, including:

  • Get Audience report data:

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceID (Workspace identifier)

      • profileUid (Social profile identifier)

      • since (Starting date for the reporting period)
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • until (Ending date of the reporting period)
        ​

  • Get Community Management report: Community management report data

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceID (Workspace identifier)

      • profileUid (Social profile identifier)

      • since (Starting date for the reporting period)
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • until (Ending date of the reporting period)
        ​

  • Get Content report: Content report data

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceID (Workspace identifier)

      • profileUid (Social profile identifier)

      • since (Starting date for the reporting period)
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • until (Ending date of the reporting period)

Competitors

Retrieve audience insights from your competitors. Competitor data is only available for Facebook pages and Instagram business accounts. The following data can be retrieved:

  • Get competitors: Retrieve competitors tracked for the social profile

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceID (Workspace identifier)

      • profileUid (Social profile identifier)
        ​

  • Get Competitor report insights: Get the aggregated competitor report for the profile

    • Required parameters:

      • organizationID (Organization identifier)

      • workspaceID (Workspace identifier)

      • profileUid (Social profile identifier)

      • since (Starting date for the reporting period)
        ​Note: Dates need to be entered in YYYY-MM-DD format (e.g., 2024-03-20)

      • until (Ending date of the reporting period)

How to interpret errors

The API uses conventional HTTP status codes. A 2xx response means success, a 4xx response points to a problem with your request such as a missing parameter, an unknown resource, or a missing API key, and a 5xx response points to a problem on the Agorapulse side.
​

Error responses carry a JSON body, except for 405, 406, and 415, which return a status only.

Example:

{   "code": 1005,   "subCode": 1104,   "message": "Media not found: pubmedia_abc123" }

  • code: Identifies the error family. A global code covers 1 for internal, 2 for unauthorized, 3 for rate limit exceeded, 4 for unprocessable input, and 5 for validation failed. Any other value identifies the component that produced the error, which is usually the feature you addressed. A request whose path matches no endpoint is rejected by the API gateway itself and returns the gateway's own code, 1013.

  • subCode: Is optional. When present, it pinpoints the exact cause within that component, and the endpoints that return one document their values.

  • message: Provides a human-readable explanation. Do not parse it in your code, because the wording can change.

Did this answer your question?