API reference
Every request, its fields and an example. For developers.
The basics
- Address:
https://api.metronoms.com/api/v1. - The API needs API access, included in the Partner program. Without it every request answers 403
API_ADDON_REQUIRED. See how to get it. - Sign in with an API key from Settings → API and AI assistants, in the header
Authorization: Bearer mtr_live_…(orX-Api-Key: mtr_live_…). A key acts as the person who made it, for the clients they work on. An MCP and Zapier key doesn’t work here (403KEY_KIND_MISMATCH). - Requests and answers are JSON, with camelCase field names.
- Each key can make 120 requests a minute and 10,000 a day. Past that the answer is 429, with a
Retry-Afterheader in seconds. - The same requests are open to AI assistants as an MCP server at
https://api.metronoms.com/mcp, with an MCP and Zapier key: that comes with the Partner program too. - For code generators: the OpenAPI description is at https://api.metronoms.com/api/v1/openapi.json.
The examples read your key from API_KEY. Set it first, or paste the key in its place.
Times and time zones
- Times are ISO 8601. A time without an offset, such as
2026-11-02T09:30, is read in the client’s own time zone (timeZonein the client list). - A time with an offset, such as
2026-11-02T09:30:00-05:00or2026-11-02T14:30:00Z, is that exact moment. - Answers give times in the client’s time zone, with its offset.
- A client with no time zone set needs an offset on every time (error
CLIENT_TIME_ZONE_MISSING), or set the time zone in the client’s Business details.
Errors
An error is JSON with a stable code for your code and a message written for people:
{ "error": "CLIENT_NOT_FOUND", "code": "CLIENT_NOT_FOUND", "message": "No client with that id in this workspace that you work on. List the clients to find the id." }- 400: something in the request is wrong; the message says what.
- 401: no key, or the key isn’t valid, was revoked or has expired.
- 402: the workspace has no plan right now (
TRIAL_EXPIRED). - 403: not allowed. For example a client login’s key (
API_KEYS_NOT_FOR_CLIENT_LOGINS), a workspace without API access (API_ADDON_REQUIRED), an MCP and Zapier key (KEY_KIND_MISMATCH), or no credits left for a post to X (AI_CREDITS_USED_UP). - 404: no such client, post or file that you can see.
- 409: the post is already being published, or has gone out and can’t be deleted.
- 429: over the limit; wait for
Retry-After.
Check your key
GET /api/v1/me: the workspace the key works in, the person who made it and the key’s name. role is owner or member; allClients is false for a Member who works on chosen clients.
{
"workspaceId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "workspaceName": "Brightside Media",
"userName": "Anna Smith", "userEmail": "anna@brightside.example", "role": "owner",
"allClients": true, "keyId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a", "keyName": "Reports script"
}List clients
GET /api/v1/clients: the clients you can post for, with each one’s time zone. In a business workspace, the one business. status is onboarding, active, paused or churned.
curl https://api.metronoms.com/api/v1/clients \
-H "Authorization: Bearer $API_KEY"{
"items": [
{ "id": "3f2b8c1e-5d6a-4c1b-9e1a-2b7c8d9e0f12", "name": "Bella Vista Bistro",
"timeZone": "America/New_York", "status": "active", "website": "https://bellavista.example" }
]
}List a client’s accounts
GET /api/v1/clients/{clientId}/accounts: the connected accounts posts can go to. network is facebook, instagram, google, threads, tiktok, linkedin, pinterest, youtube, x, bluesky or mastodon. status is connected, or needsReconnect when the network no longer accepts the connection (reconnect it in the app). No network’s tokens are ever included.
{
"items": [
{ "id": "8a1d2f30-0b4c-4e5f-9a6b-7c8d9e0f1a2b", "clientId": "3f2b8c1e-5d6a-4c1b-9e1a-2b7c8d9e0f12",
"network": "instagram", "name": "bellavistabistro", "status": "connected" }
]
}Get a client’s figures
GET /api/v1/clients/{clientId}/analytics?from=2026-10-01&to=2026-10-31: followers, follower growth, reach, views, impressions, engagement and posts published, in total and per network. Days are counted in the client’s time zone. from and to are dates and both are optional: the default is the last 30 days, and a request covers at most a year. The same question within ten minutes gets the same answer.
{
"clientId": "3f2b8c1e-5d6a-4c1b-9e1a-2b7c8d9e0f12", "from": "2026-10-01", "to": "2026-10-31",
"timeZone": "America/New_York", "followers": 13240, "followerGrowth": 182,
"reach": 48210, "views": 95330, "impressions": 95330, "engagement": 2140, "engagementRate": 4.4,
"postsPublished": 27,
"networks": [
{ "network": "instagram", "accounts": 1, "followers": 6120, "reach": 21980, "views": 50410,
"engagement": 1310, "postsPublished": 9 }
]
}A figure a network doesn’t give is null.
Add a photo or video
POST /api/v1/media: copies a photo or video into the client’s media library and answers its id, to use in a post’s mediaIds. Up to 200 MB; photos and videos only. Send the file as multipart/form-data (field file), or JSON with a public address (url). clientId names the client’s library; without it the file goes to your agency’s shared media (a Member who works on several clients must give it).
curl -X POST https://api.metronoms.com/api/v1/media \
-H "Authorization: Bearer $API_KEY" \
-F "file=@croissants.jpg" \
-F "clientId=3f2b8c1e-5d6a-4c1b-9e1a-2b7c8d9e0f12"curl -X POST https://api.metronoms.com/api/v1/media \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/croissants.jpg","clientId":"3f2b8c1e-5d6a-4c1b-9e1a-2b7c8d9e0f12"}'{
"id": "c41e7a02-6f3b-4d8e-a1c2-5b6d7e8f9a0b", "clientId": "3f2b8c1e-5d6a-4c1b-9e1a-2b7c8d9e0f12",
"url": "https://…", "type": "image", "width": 1080, "height": 1350,
"durationSeconds": null, "fileName": "croissants.jpg"
}url is a temporary link to look at the file (about an hour). Use the id in posts, never the link.
Create a post
POST /api/v1/posts: a draft, a post scheduled for a time, or one published now, for one client. It goes through the same checks as the post window and your approval rules, so it may come back as awaitingApproval.
clientId(required): the client.accountIds: the client’s accounts to post to. Required unless it’s a draft.text: the post’s text.link: a link, kept apart from the text so each network shows it its own way.addWebsiteLink:falseto leave the client’s website link off the post. Without alink, a post gets the client’s website from Business details as its link (at the end of the text where links work, as Google’s button, as the pin’s link), unless the client’s Website link on posts setting is off.mediaIds: photos and videos fromPOST /api/v1/media, in order.media: photos or videos by public address, as[{ "url": "https://…" }], copied in aftermediaIds. Up to 20 files in all.scheduledAt: when to publish (see Times). Required unlesspublishNowordraftis true. It must be in the future.publishNow:trueto publish straight away.draft:trueto save a draft. Nothing is published until someone schedules it in the app.facebookandinstagram:{ "format": "post" },"reel"or"story". Leave them out for the usual choice (on Instagram a single video is a Reel).clientApprovesFirst:trueto hold a scheduled post until the client approves it. The client is emailed a link, andclientApprovalin the answer says whether the email went.
curl -X POST https://api.metronoms.com/api/v1/posts \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6c0d1f9e-2a3b-4c5d-8e9f-0a1b2c3d4e5f" \
-d '{"clientId":"3f2b8c1e-5d6a-4c1b-9e1a-2b7c8d9e0f12","accountIds":["8a1d2f30-0b4c-4e5f-9a6b-7c8d9e0f1a2b"],"text":"Fresh pastries all weekend.","mediaIds":["c41e7a02-6f3b-4d8e-a1c2-5b6d7e8f9a0b"],"scheduledAt":"2026-11-02T09:30"}'{
"id": "5e9b0c2d-7a1f-4b3e-8c6d-2f4a6b8c0d1e", "status": "scheduled",
"scheduledAt": "2026-11-02T09:30:00-05:00", "timeZone": "America/New_York", "clientApproval": null
}- Send an
Idempotency-Keyheader (a UUID is ideal, up to 128 characters) so a retry never makes a second post: the same key gives back the same post for 24 hours. - TikTok accounts can only be in a draft (
TIKTOK_NEEDS_COMPOSER): TikTok asks a person to choose who can see the video and agree to its terms, in the post window. - Reddit accounts can only be in a draft too (
REDDIT_NEEDS_COMPOSER): each Reddit post names its community and has a title, chosen in the post window. - A post to X uses credits when it goes out: 2, or 15 with a link. Without enough left this month, it’s refused with
AI_CREDITS_USED_UP.
List posts
GET /api/v1/posts?clientId=…&from=2026-11-01&to=2026-11-30&status=scheduled,failed: posts on the calendar between two times, oldest first. All parameters are optional.
clientId: one client’s posts only. Without it, times without an offset are read as UTC.fromandto: a date (the whole day counts forto) or a time. The default is the last 7 days and the next 30; at most 93 days at a time.status: comma-separated draft, scheduled, awaitingApproval, publishing, published, partiallyPublished, failed or canceled.limit(default 100, up to 500) andoffset.hasMorein the answer says whether there are more.
Each post has its id, status, scheduledAt, the start of its text, its networks, mediaCount, links to the published posts, an error sentence when it failed, and imported for posts brought in from the network.
Get a post
GET /api/v1/posts/{id}: one post with its status, time, text, link, media and, under results, how it went on each account: published, failed, publishing, or pending (the network is still reviewing it, as Google does), with the link to the post or a sentence saying what went wrong.
{
"id": "5e9b0c2d-7a1f-4b3e-8c6d-2f4a6b8c0d1e", "status": "published",
"scheduledAt": "2026-11-02T09:30:00-05:00", "text": "Fresh pastries all weekend.",
"results": [
{ "accountId": "8a1d2f30-0b4c-4e5f-9a6b-7c8d9e0f1a2b", "network": "instagram", "status": "published",
"url": "https://www.instagram.com/p/…", "error": null }
]
}A post made through the app keeps one id from scheduling to publishing. Drafts and imported posts have their own.
Delete a post
DELETE /api/v1/posts/{id}: cancels a scheduled post (or one waiting for approval), or deletes a draft. The answer is 204. A post that has gone out, or is going out, answers 409. Cancelling a post that is already cancelled is not an error.
Post statuses
draft: saved, not scheduled.scheduled: waiting for its time.awaitingApproval: waiting for an approval in the app, or for the client’s.publishing: going out now.published: out on every account.partiallyPublished: out on some accounts and failed on others.failed: didn’t go out;errorsays why.canceled: cancelled before it went out.
List recent events
GET /api/v1/events?type=post.published,post.failed: what happened in the last 30 days, newest first. It’s made for tools that check every few minutes for something new: each event has an id that never changes, so a tool can skip the events it has already seen.
type(required): one or more of these, separated by commas.post.published: a post went out on an account. A post sent to three accounts is three events.post.statusis published, or pending while the network is still reviewing it (as Google does).post.failed: a post failed on an account, andpost.errorsays why. A post that failed before reaching any account is one event with no account. If it fails again after a retry, that’s a new event.report.ready: a monthly report is ready: one made automatically each month, or one sent to the client. Copies made while working on a report don’t count.lead.created: a company was added to the CRM, with its first contact and its deal. Only for Owners and Members who work on all clients (otherwiseAGENCY_ONLY), on plans with the CRM.clientId: only this client’s post and report events. Leads belong to the whole workspace, so leave it out forlead.created.limit: up to 100, the default.hasMorein the answer says whether there were more.
Each event has its id, type, at (when it happened, in the client’s time zone; UTC for leads), clientId and clientName, and one of these:
post: the post’sid(as inGET /api/v1/posts/{id}),status,network,accountId,accountName,text,link,mediaCount,url(the published post),error,format,scheduledAtandappUrl(the calendar in the app, on the post’s day).report: itsid,year,month,period(such as October 2026),automatic(true when made automatically),sentAt,sentTo,postsPublished,reach,engagementsandappUrl(the report in the app).lead: the company’sid,name,website,phone,email,city,region,country,category,source(manual, findLeads or import),contact(name,title,email,phone),deal(id,title,stage,status,monthlyValue,oneTimeValue,currency) andappUrl(the company in the CRM).
curl "https://api.metronoms.com/api/v1/events?type=post.published,post.failed&limit=50" \
-H "Authorization: Bearer $API_KEY"{
"items": [
{ "id": "post.failed:5e9b0c2d7a1f4b3e8c6d2f4a6b8c0d1e:b7c8d9e00f1a4b2c8d3e4f5a6b7c8d9e:1793626241",
"type": "post.failed", "at": "2026-11-02T09:30:41-05:00", "timeZone": "America/New_York",
"clientId": "3f2b8c1e-5d6a-4c1b-9e1a-2b7c8d9e0f12", "clientName": "Bella Vista Bistro",
"post": { "id": "5e9b0c2d-7a1f-4b3e-8c6d-2f4a6b8c0d1e", "status": "failed", "network": "facebook",
"accountName": "Bella Vista Bistro", "text": "Fresh pastries all weekend.", "url": null,
"error": "The connection to Facebook has expired. Reconnect the account, then press Retry." } },
{ "id": "post.published:5e9b0c2d7a1f4b3e8c6d2f4a6b8c0d1e:8a1d2f300b4c4e5f9a6b7c8d9e0f1a2b",
"type": "post.published", "at": "2026-11-02T09:30:38-05:00", "timeZone": "America/New_York",
"clientId": "3f2b8c1e-5d6a-4c1b-9e1a-2b7c8d9e0f12", "clientName": "Bella Vista Bistro",
"post": { "id": "5e9b0c2d-7a1f-4b3e-8c6d-2f4a6b8c0d1e", "status": "published", "network": "instagram",
"accountName": "bellavistabistro", "text": "Fresh pastries all weekend.",
"url": "https://www.instagram.com/p/…", "error": null } }
],
"hasMore": false
}The example leaves out some fields to keep it short. A field with nothing in it is null.