Calendar

View and manage your social media content calendar with scheduled posts and publishing timeline.

The Calendar endpoint provides access to your social media calendar, allowing you to retrieve scheduled posts, view publishing timelines, and manage your content schedule across all connected social networks and campaigns.

One request returns every post in the date window. The response is not paginated. fromDate and toDate cannot span more than 60 days. A longer range fails with Time period should not exceed 60 days. Each message in Messages includes the full Message body.

Get Calendar

Example Request

curl -i https://api.oktopost.com/v2/calendar -X POST
    -d fromDate=2018-02-01 \
    -d toDate=2018-02-20

Example Result

{
    "Campaigns": {
        "002000000000001": {
            "Color": "#3492bf",
            "Id": "002000000000001",
            "Name": "2018-02 General Campaign",
            "Status": "complete"
        }
    },
    "Credentials": {
        "003-001000000000001-1234": {
            "BoardOnly": 0,
            "DisplayName": "OktoTest1",
            "ExpiresOn": "3999-12-31 23:59:59",
            "Id": "003-001000000000001-1234",
            "ImageLink": "https://s3.amazonaws.com/dev-com-oktopost-app-credential-pictures/Facebook-1234.png",
            "IsHidden": 0,
            "Name": "OktoTest  (Page)",
            "Network": "Facebook",
            "NetworkAccountId": "1234",
            "NetworkUsername": "1234",
            "ParentCredentialId": "003-001000000000001-100001878919601",
            "Status": "valid"
        }
    },
    "Media": [],
    "Messages": {
        "005000000000001": {
            "CampaignId": "002000000000001",
            "Clicks": 0,
            "Converts": 0,
            "Description": "Oktopost is a social media management platform designed to publish social messages, engage with social sales and support employee social advocacy",
            "Id": "005000000000001",
            "ImageUrl": "https://s3.amazonaws.com/dev-com-oktopost-app-message-pictures/0010000000000015a8acb3e6e9d47.59722266/imac-from-side.jpg",
            "IsBoardMessage": 0,
            "LinkTitle": "Social Media Management for B2B Marketing - Oktopost",
            "LinkUrl": "https://www.oktopost.com/",
            "MediaIds": [],
            "Message": "hello https://www.oktopost.com/",
            "MessageLength": 31,
            "Network": "Facebook",
            "Status": "default",
            "Subject": "",
            "Type": "link-attachment",
            "Url": ""
        }
    },
    "Posts": {
        "004000000000001": {
            "CampaignId": "002000000000001",
            "Clicks": 0,
            "ContentSource": "User",
            "Converts": 0,
            "CredentialIds": [
                "003-001000000000001-1234"
            ],
            "Id": "004000000000001",
            "MessageId": "005000000000001",
            "Network": "Facebook",
            "Source": "UI",
            "StartDateTime": "2018-02-19 08:03:00",
            "Status": "complete",
            "ApproveStatus": "Approved",
            "TotalCount": 1
        }
    },
    "Postlogs": [
        {
            "Id": "007000000000001",
            "CredentialId": "003-001000000000001-1234",
            "PostId": "004000000000001",
            "MessageId": "005000000000001",
            "Status": "success",
            "RemoteUrl": "https://www.facebook.com/1234/posts/xxxx",
            "PublishedDate": "2018-02-19 08:03:00"
        }
    ],
    "CustomEvents" : [],
    "Result": true
}

Postlogs lists one entry per profile the post was sent to. Each entry has Id, CredentialId, PostId, MessageId, Status, RemoteUrl, and PublishedDate. It does not include RemoteId. To read the network post id, use one of:

List by Post Id: GET /v2/postlog?postId=
List Posts with withPostlogs=1: Postlogs is embedded on each item
Get Post with postlogs=1: Postlogs is returned beside Post

Parameters

Param	Description
fromDate	Required. Format: YYYY-MM-DD. The range from `fromDate` to `toDate` cannot exceed 60 days.
toDate	Required. Format: YYYY-MM-DD. The range from `fromDate` to `toDate` cannot exceed 60 days.
filters	Optional. JSON Object. See structure below

Filters

The following parameters can be used to build the filters object in your request.

Param	Type	Description
campaigns	Array	See Campaigns API
credentials	Array	See Profiles API
messages	Array	See Messages API
networks	Array	Options: Facebook, Twitter, LinkedIn, Instagram, YouTube, and TikTok
postSources	Array	See Posts API
statuses	Array	See Posts API
users	Array	See Users API
campaignTags	Array	Tag `Id` values from Tags. Keeps posts in campaigns that have one of these tags.
messageTags	Array	Tag `Id` values from Tags. Keeps posts whose message has one of these tags.
teams	Array	Campaign team ids. See Teams. Keeps posts whose campaign belongs to one of these teams.
hasFirstComment	Boolean	When `true`, only posts that have a first comment. When `false`, only posts that do not. Omit the field to skip this filter.
promotion	Array	Options: `promoted`, `organic`, `unknown`
showArchived	Boolean	When `true`, include posts from archived campaigns. Defaults to `false`.

Example request with filters

curl -i https://api.oktopost.com/v2/calendar -X POST
    -d fromDate=2018-02-01 \
    -d toDate=2018-02-20 \
    -d filters={"campaigns": ["002000000000001"]}

Custom Calendar Events

Custom events allow you to add non-holiday events to the calendar, including campaign milestones, meetings, product launches, deadlines, and reminders.

Get Custom Calendar Event

Get the data for a single custom calendar event.

Example Request

curl -i "https://api.oktopost.com/v2/calendar/custom-events?id=0CE00000000000x"

Example Result

{
    "Result": true,
    "Item": {
        "ID": "0CE00000000000x",
        "Created": "2026-08-01 09:30:00",
        "Modified": "2026-08-01 09:30:00",
        "AccountID": "00100000000000x",
        "Title": "Product launch",
        "Description": "Launch the new product website.",
        "Color": "#3492bf",
        "StartDateTime": "2026-08-10 12:00:00",
        "EndDateTime": "2026-08-10 13:00:00",
        "Campaigns": [
            {
                "Id": "00200000000000x",
                "Name": "Product Launch"
            }
        ]
    }
}

Parameters

Prop	Description	Required	Default
id	The custom calendar event ID.	√	-

A 404 error is returned when the event does not exist or the authenticated user does not have access to it.

Get Custom Calendar Events

List custom calendar events that are visible to the authenticated user.

When no campaign IDs are provided, all events available to the authenticated user are returned.

Example Request

curl -i https://api.oktopost.com/v2/calendar/custom-events \
    --data-urlencode after=1785542400 \
    --data-urlencode before=1788220799 \
    --data-urlencode "campaignIds[]=00200000000000x" \
    --data-urlencode _page=0 \
    --data-urlencode _count=25 \
    --data-urlencode _order=startDateTime

Example Result

{
    "Result": true,
    "Total": 2,
    "Items": [
        {
            "ID": "0CE00000000000x",
            "Created": "2026-08-01 09:30:00",
            "Modified": "2026-08-01 09:30:00",
            "AccountID": "00100000000000x",
            "Title": "Product launch",
            "Description": "Launch the new product website.",
            "Color": "#3492bf",
            "StartDateTime": "2026-08-10 12:00:00",
            "EndDateTime": "2026-08-10 13:00:00",
            "Campaigns": [
                {
                    "Id": "00200000000000x",
                    "Name": "Product Launch"
                }
            ]
        },
        {
            "ID": "0CE00000000000y",
            "Created": "2026-08-02 11:00:00",
            "Modified": "2026-08-02 11:00:00",
            "AccountID": "00100000000000x",
            "Title": "Campaign review",
            "Description": "Review the first week of campaign performance.",
            "Color": "#9b59b6",
            "StartDateTime": "2026-08-17 10:00:00",
            "EndDateTime": "2026-08-17 11:00:00",
            "Campaigns": [
                {
                    "Id": "00200000000000x",
                    "Name": "Product Launch"
                }
            ]
        }
    ]
}

Parameters

Prop	Description	Required	Default
ids	An array of custom calendar event IDs.	-	All events
campaignIds	An array of campaign IDs. See Campaigns API.	-	All accessible campaigns
after	The beginning of the requested date range as a Unix timestamp.	-	-
before	The end of the requested date range as a Unix timestamp.	-	-
_page	The current page.	-	0
_count	The number of events returned per page. Options: `25`, `50`, or `100`.	-	25
_order	Options: created, modified, startDateTime.	-	created

Example Request by Event IDs

curl -i -G https://api.oktopost.com/v2/calendar/custom-events \
    --data-urlencode "ids[]=0CE00000000000x" \
    --data-urlencode "ids[]=0CE00000000000y"

Add Custom Calendar Event

Create a new custom calendar event.

When endDate is not provided, a single-day event is created.

Parameters

Prop	Description	Required	Default
title	The event title. Maximum 80 characters.	√	-
description	The event description. Maximum 2,000 characters, excluding HTML tags.	-	Empty
startDate	The event start date and time as a Unix timestamp.	√	-
endDate	The event end date and time as a Unix timestamp.	-	-
campaignIds	An array of campaign IDs associated with the event. See Campaigns API.	-	Empty

Example Request

curl -i https://api.oktopost.com/v2/calendar/custom-events -X POST \
    -d title="Product launch" \
    -d description="Launch the new product website." \
    -d startDate=1786352400 \
    -d endDate=1786356000 \
    -d "campaignIds[]=00200000000000x"

Example Result

{
    "Result": true,
    "Item": {
        "ID": "0CE00000000000x",
        "Created": "2026-08-01 09:30:00",
        "Modified": "2026-08-01 09:30:00",
        "AccountID": "00100000000000x",
        "Title": "Product launch",
        "Description": "Launch the new product website.",
        "Color": "#3492bf",
        "StartDateTime": "2026-08-10 12:00:00",
        "EndDateTime": "2026-08-10 13:00:00",
        "Campaigns": [
            {
                "Id": "00200000000000x",
                "Name": "Product Launch"
            }
        ]
    }
}

Edit Custom Calendar Event

Update an existing custom calendar event.

Only the id parameter is required. Properties that are not included in the request retain their existing values.

Parameters

Prop	Description	Required	Default
id	The custom calendar event ID.	√	-
title	The event title. Maximum 80 characters.	-	Current value
description	The event description. Maximum 2,000 characters, excluding HTML tags.	-	Current value
startDate	The event start date and time as a Unix timestamp.	-	Current value
endDate	The event end date and time as a Unix timestamp.	-	Current value
campaignIds	An array of campaign IDs associated with the event. See Campaigns API.	-	Current value

Example Request

curl -i https://api.oktopost.com/v2/calendar/custom-events -X PUT \
    -d id="0CE00000000000x" \
    -d title="Updated product launch" \
    -d endDate=1786356000 \
    -d "campaignIds[]=00200000000000x"

Example Result

{
    "Result": true,
    "Item": {
        "ID": "0CE00000000000x",
        "Created": "2026-08-01 09:30:00",
        "Modified": "2026-08-02 14:20:00",
        "AccountID": "00100000000000x",
        "Title": "Updated product launch",
        "Description": "Launch the new product website.",
        "Color": "#3492bf",
        "StartDateTime": "2026-08-10 12:00:00",
        "EndDateTime": "2026-08-10 13:00:00",
        "Campaigns": [
            {
                "Id": "00200000000000x",
                "Name": "Product Launch"
            }
        ]
    }
}

Delete Custom Calendar Event

Delete a custom calendar event.

Parameters

Prop	Description	Required	Default
id	The custom calendar event ID.	√	-

Example Request

curl -i https://api.oktopost.com/v2/calendar/custom-events -X DELETE \
    -d id="0CE00000000000x"

Example Result

{
    "Result": true
}

A 404 error is returned when the event does not exist.

A 403 error is returned when the authenticated user does not have permission to delete the event.

On this page