Sponsors API

[filiptronicek]

There are some very limited queries for the sponsor listing and tiers available through the GraphQL API, but there is no way to get info like:

• Who sponsors this user?
• Who does this user sponsor?
• For how much does this user sponsor me?

I made a REST API that mimics what I would love to see being implemented officially, so for inspiration, here it is: https://github.com/filiptronicek/gh-sponsors-api

[cheshire137]

Hi @filiptronicek! I'm one of the developers on the Sponsors team.

Who sponsors this user?

This should be answerable by the new Sponsorable.sponsors connection. For example:

query {
  user(login:"filiptronicek") {
    ... on Sponsorable {
      sponsors(first: 10) {
        totalCount
        nodes {
          ... on User { login }
          ... on Organization { login }
        }
      }
    }
  }
}

You can try this in the GraphQL Explorer.

Who does this user sponsor?
For how much does this user sponsor me?

These are in progress, stay tuned!

[vp4140]

Wanted to know, how much money has the sponsorer sponsored to a project or person. Is there any GraphQl to fetch that?

[vp4140]

@cheshire137 Can you please help with the above question? I am currently working with Open collective to solve a major problem.
https://opencollective.com/collective/projects/layoffs-in-tech-industry-and-f.

[cheshire137]

how much money has the sponsorer sponsored to a project or person

Hi! Does the Sponsorable.totalSponsorshipAmountAsSponsorInCents field (see https://github.com/orgs/community/discussions/3818#discussioncomment-4637795 below) help?

[vp4140]

Hi @cheshire137, I don't manage sponsorships for the organisations or persons that I am fetching data for. Lets say there is user https://github.com/speth , username: speth. I want to know how much his money he has received from sponsors in specific duration.

Tried these query below, But I am receiving no nodes
query = """
query ($user: String!) {
user(login: $user) {
sponsors(first: 100) {
edges {
node {
... on Organization {
id
email
}
... on User {
id
email
}
}
}
}
}
}
"""

    Output: {'data': {'user': {'sponsorshipsAsSponsor': {'nodes': []}}}} 

[cheshire137]

I don't manage sponsorships for the organisations or persons that I am fetching data for

I want to know how much his money he has received from sponsors

Ooh, you won't be able to do that, we intentionally disallow it. How much money another user or organization has received via GitHub Sponsors is private information. You're only able to look up how much someone has earned if you are that user or if you're an admin of the organization who received the sponsorships.

[cheshire137]

Who does this user sponsor?

This can be answered by the new Sponsorable.sponsoring connection! For example:

query {
  user(login: "cheshire137") {
    sponsoring(first: 10) {
      totalCount
      nodes {
        ... on User { login }
        ... on Organization { login }
      }
    }
  }
}

See docs for the Sponsorable interface: https://docs.github.com/en/graphql/reference/interfaces#sponsorable

[filiptronicek]

Awesome! I'm glad these features are actively being implemented.

[Gummibeer]

Where's the difference betweensponsorshipsAsMaintainer and sponsors? 🤔
From what they are doing and even the query looks nearly the same.

[cheshire137]

It's whether you want the users/orgs directly or the sponsorships. If you want to know other data that's on each sponsorship, for data you're allowed to know, the sponsors/sponsoring connections can't tell you that.

See the reference on fields available on a Sponsorship: https://docs.github.com/en/graphql/reference/objects#sponsorship

[mrousavy]

Hey! Is there also a REST API for this, or is this planned to be added in Octokit/Probot? Trying to figure out is a user is sponsoring the repo owner.

[cheshire137]

Okay, last piece!

For how much does this user sponsor me?

The new field sponsorshipForViewerAsSponsorable will let you learn this. For example:

query {
  user(login:"someoneSponsoringYou") {
    ... on Sponsorable {
      sponsorshipForViewerAsSponsorable {
        tier {
          name
          monthlyPriceInCents
        }
      }
    }
  }
}

[4Ferdy]

.

[PEZ]

@cheshire137 Thanks for providing the examples for how to use. I haven't gone to GraphQL Academy (rather, it is the first time I try this) so wouldn't have come far w/o the examples.

When I run this on my own user I can get all sponsors and all data. However when I try with my team mate, I only get the sponsorshipForViewerAsSponsorable data for some of his sponsors. I guess this is by design, but the pattern seems a bit random. For instance, I happen to sponsor my team mate and fetching his sponsors, the sponsorshipForViewerAsSponsorable is null for my entry, but open for other user accounts. Do you know what I can expect here? And is there some way my team mate and I can open this data up for each other's tokens? That would smoothen things up considerably.

[cheshire137]

Thank you for the report! We're looking into this. I'm wondering how you were hitting the API, were you authenticating with an OAuth token? If so, what scopes did you have?

[cheshire137]

Ah, to clarify: you're hitting sponsorshipForViewerAsSponsorable and not getting any results. That field is described as:

The sponsorship from this user/organization to the viewer; that is, the sponsorship you're receiving. Only returns a sponsorship if it is active.

Are you querying sponsorshipForViewerAsSponsorable on a user/org who is sponsoring you? It should be null if you query it on anyone who is not your sponsor.

[SupremeTechnopriest]

@cheshire137 Is there a way to get all sponsors and not just active ones via graphql? Trying to use the API to create a list of all sponsors and I'm not seeing anything in the schema. It seems like the query only returns donors for the current month and not one time donors from previous months.

Thanks!

[cheshire137]

Hi! I think we don't have a way to get your past sponsors right now, but that's a reasonable idea. I'll record that for us to look at internally, thanks!

[SupremeTechnopriest]

Thanks for the clarification. I will export a report and parse the data I need by hand from there for now.

[cheshire137]

Oh you know, one roundabout way of getting this from the API might be to hit the sponsorsActivities endpoint. There should be activities for starting and stopping a sponsorship, and you can see who the sponsor was for those. This should be the same kind of data you see on the https://github.com/sponsors/USER/dashboard/activity page, the Your Sponsors > Activity Feed page in your Sponsors dashboard.

• https://docs.github.com/en/graphql/reference/objects#sponsorsactivity
• https://docs.github.com/en/graphql/reference/interfaces#sponsorable

[SupremeTechnopriest]

Cool! I will give that a shot. If I end up with a query that works Ill post it here in case anyone else needs it.

[SupremeTechnopriest]

I got pretty close to a dataset that is usable...

query { 
  user(login: "supremetechnopriest") {
    sponsorsActivities(first:100, period: ALL) {
      totalCount
      nodes {
        action
        sponsor {
          ... on User {
            login
            avatarUrl
            name
            url
            websiteUrl
          }
          ... on Organization {
            login
            avatarUrl
            name
            url
            websiteUrl
          }
        }
      }
    }
  }
}

The only problem is that organizations that have donated but have oauth app restrictions turned on cause an error in the result set.

"errors": [
    {
      "type": "FORBIDDEN",
      "path": [
        "user",
        "sponsorsActivities",
        "nodes",
        0
      ],
      "extensions": {
        "saml_failure": false
      },
      "locations": [
        {
          "line": 10,
          "column": 7
        }
      ],
      "message": "Although you appear to have the correct authorization credentials, the `edgemesh` organization has enabled OAuth App access restrictions, meaning that data access to third-parties is limited. For more information on these restrictions, including how to enable this app, visit https://docs.github.com/articles/restricting-access-to-your-organization-s-data/"
    }
]

This does not appear to be a limitation on the Sponsors schema. Looks like I'm back to manual exports for now. If you could keep me posted on the addition of a period: ALL clause on the Sponsors schema that would be great!

[fanyoumei]

Hi @cheshire137, I am new to graphql, but for now, I have still not found a way to solve my problems. Is there any way that I can retrieve how much sponsor money has got in a specific time duration by username?

[Tyrrrz]

@cheshire137 I'm not sure if that actually returns enough data to calculate total donations per person.

For example, in a situation where I have: monthly subscribers, on-and-off monthly subscribers (e.g. stopped supporting, then resumed later), one-time supporters, monthly subscribers who also made one-time donations – what is the easiest way to get the total donated amount for a period, from each individual user or organization? It would be very useful if the sponsor { } interface contained something like totalDonatedInCents for some period. Right now, I think, the API makes it really hard to get this information.

As an aside, it would be nice to have this info also presented for the maintainer in the UI, on the Sponsors tab of the dashboard.

[KoKin941112]

@cheshire137 I copied your code with a valid login, but there was no output. Could you please have a look?

[cheshire137]

Hi there! I wanted to give an update that there are now more specific date arguments you can use in place of the existing period argument: since and until. See for example:

-- https://docs.github.com/en/graphql/overview/explorer

[cheshire137]

I copied your code with a valid login, but there was no output. Could you please have a look?

@KoKin941112, hmm, have you ever sponsored JuliaLang (from your screenshot) as yourself? I would only expect for you to see results in your sample query if you had.

[cheshire137]

what is the easiest way to get the total donated amount for a period, from each individual user or organization?

totalDonatedInCents

have this info also presented for the maintainer in the UI

@Tyrrrz, thank you for this! I'm making an issue about revealing this information, and I'll keep you posted here if we implement it. The closest I can think right now is the totalRecurringMonthlyPriceInCents on a SponsorshipConnection:

-- https://docs.github.com/en/graphql/overview/explorer

This example shows that I'm paying $5 a month to a particular maintainer. You can use these fields with sponsorshipsAsMaintainer and sponsorshipsAsSponsor for example. This doesn't let you filter by time, however.

[lowlighter]

Hi @cheshire137 !

Is there a way to know through the GraphQL API whether a sponsorship is private or public ?
I couldn't find any filter/attributes in the GraphQL explorer mentioning this

Same for sponsorsActivities, is there a way to get visibility on action: "NEW_SPONSORSHIP" ?

Thanks a lot for your response

[cheshire137]

Hi! For a sponsorship, there's a privacyLevel enum field; see https://docs.github.com/en/graphql/reference/objects#sponsorship.

For a Sponsors activity, there's no way to tell this I believe. 🤔 I'll file an issue on our side to look at adding such, thanks! Here are the SponsorsActivity docs, in case they're still of use: https://docs.github.com/en/graphql/reference/objects#sponsorsactivity

[lowlighter]

Thanks a lot for your reply!

privacyLevel is exactly what I needed 😄 !

Let me know if you ever advance on a similar feature for SponsorsActivity or if you implement a way to retrieve past sponsors directly through Sponsorships object, I'll be sure to test it 👍 !

[fanyoumei]

Hi @cheshire137! Me again lol. I want to ask you is there any possibility through the GraphQL API to know the number of sponsors the user has over a specific time? For instance, how many sponsors does the user has during April 2022? I try a lot but only can get the sponsor total count for current.

[cheshire137]

But I am a little confused, in user(login: "maintainerLoginHere"), how can I know if the user is a maintainer or not?

Ooh, the sponsorsActivities field will only return results where you're the sponsor or the maintainer in the relationship. So like I'm sponsoring zkat, so I could load user(login: "zkat") { sponsorsActivities and see activities about my sponsorship of them. They could also load that same field and see activities from any sponsor, since they're the maintainer and are privy to that info.

Are you wanting to get public sponsorship information for an unrelated user/org, like someone that isn't you?

[cheshire137]

how can I know if the user is a maintainer or not?

This can be answered via Sponsorable.hasSponsorsListing:

[fanyoumei]

Thank you so much for your reply! Yes, I am trying to get public sponsorship information for other users, this is what I was trying to get! 👍

[cheshire137]

Yes, I am trying to get public sponsorship information for other users

Gotcha. There's no good way in the API right now to get at sponsorship info over time for someone else. I'd want to discuss with the team if that were something we'd want to expose, though. While you could visit someone's GitHub profile daily and see one day "they have sponsors A, B, C" then the next day "today, they have sponsors B, C, and D" to know that they gained sponsor D and lost sponsor A, it changes things somewhat to think of publicizing that detail in a consumable, aggregate way such as via an API that would let you query "who exactly did this maintainer have as a sponsor on this date," or "in what month did so-and-so stop sponsoring maintainer X". 🤔

Can you share what you're wanting to build with this data? Maybe there's something else that would be reasonable to expose in the API that could help.

[fanyoumei]

I understand that such data is difficult to publish properly, so I am glad that you can discuss it within the team.

We are the team that conducted empirical studies on GitHub Discussions and GitHub Sponsors mentioned in this blog.
https://github.blog/2022-07-20-heres-how-academic-research-is-shaping-github-discussions/

As a second study on GitHub Sponsors, we would like to analyze how appealing on SNS affects sponsor acquisition, similar to this paper.
https://people.engr.ncsu.edu/ermurph3/papers/icse19toilet.pdf

[sheilalarmour]

I don’t know! Let me think about it! Sent from Mail<https://go.microsoft.com/fwlink/?LinkId=550986> for Windows From: Sarah ***@***.***> Sent: Friday, July 22, 2022 2:50 PM To: ***@***.***> Cc: ***@***.***> Subject: Re: [github-community/community] Sponsors API (Discussion #3818) Yes, I am trying to get public sponsorship information for other users Gotcha. There's no good way in the API right now to get at sponsorship info over time for someone else. I'd want to discuss with the team if that were something we'd want to expose, though. While you could visit someone's GitHub profile daily and see one day "they have sponsors A, B, C" then the next day "today, they have sponsors B, C, and D" to know that they gained sponsor D and lost sponsor A, it changes things somewhat to think of publicizing that detail in a consumable, aggregate way such as via an API that would let you query "who exactly did this maintainer have as a sponsor on this date," or "in what month did so-and-so stop sponsoring maintainer X". 🤔 Can you share what you're wanting to build with this data? Maybe there's something else that would be reasonable to expose in the API that could help. — Reply to this email directly, view it on GitHub<https://github.com/orgs/github-community/discussions/3818#discussioncomment-3208754>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AKNOOWXXEKLZA4UQJN6CUTDVVL3RZANCNFSM43IJIA2Q>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[lowlighter]

Hi @cheshire137

Is there a way to get (or recompute) the total amount you gave as a sponsor ?
I'm trying to get the same value which is displayed on https://github.com/sponsors/explore page:

As sponsorshipsAsSponsor only list active sponsorships, if a sponsorship has been stopped it's not possible to get any informations about it anymore since there are no equivalent to sponsorsActivities as far as I know

Thanks for your answer

[cheshire137]

Hi there! This is a great question and I don't think we expose this via the API. I'll make an issue internally about it, thanks for bringing it up!

[lowlighter]

Cool, thanks a lot 👍 !

[cheshire137]

Hi again! There's now a Sponsorable.totalSponsorshipAmountAsSponsorInCents field you can query on users and organizations in the GraphQL API. You'll only get a value back when querying the field for yourself or for an organization you're admin or billing manager of.

-- https://docs.github.com/en/graphql/overview/explorer

query {
  viewer {
    login
    totalSponsorshipAmountAsSponsorInCents
  }
}

[lowlighter]

@cheshire137 It works perfectly and succedeed to reproduce an embeddable SVG of it !

However I have yet another question.
I'm using a query similar to below to list users/organizations I'm currently sponsoring or sponsored in the past:

query SponsorshipsAll {
  user(login: "lowlighter") {
    sponsorshipsAsSponsor(first: 100, activeOnly: false, orderBy: {field: CREATED_AT, direction: DESC}) {
      nodes {
        sponsorable {
          ... on User {
            login
          }
          ... on Organization {
            login
          }
        }
      }
    }
  }
}

As you can see on the image above, users are indeed appearing, but I also used to sponsor an organization which is denoland but it doesn't get listed from the query result. I think this is because they quitted the GitHub sponsors program (it's not possible to sponsor them anymore through GitHub) but the data should still be accessible since the achievement still reference it:

Is it an error from my query (or missing scope ?), or is it a bug from the GraphQL API ? (unless it's intended ?)

Thanks for your answer and thanks again for exposing Sponsorable.totalSponsorshipAmountAsSponsorInCents !

[catgirlinspace]

@cheshire137 hiya!! Is there a rest api equivalent for GitHub sponsors? I tried looking around in the docs but couldn't find anything. I'm not too comfortable yet with using GraphQL so I kinda try to avoid it, heh.

[not-ivy]

https://github.com/filiptronicek/gh-sponsors-api

[cheshire137]

I'm just now seeing this, sorry! I don't think there's any GitHub Sponsors support in the REST API, it's all in the GraphQL API to my knowledge. Maybe there's some Sponsors support in the REST API around webhooks. 🤔

[neil-morrison44]

Hi - I'm trying to get the total number of active sponsors on my account
So this works fine:

{
  user(login: "neil-morrison44") {
    ... on Sponsorable {
      sponsors(first: 10) {
        totalCount
      }
    }
  }
}

In the explorer - trouble is I'm trying to do it inside a GitHub workflow, which only ever gives me the public count (even when using a PAT linked to my account, which I wasn't expecting).

Is there a particular permission to enable this somehow? or, even better, a different query which just lists the same total count the web pages do (without leaking private sponsor details)?

[needim]

If anyone still needs it;

This query will:

• get viewer's sponsors with tiers
• get viewer's sponsorships to another user or org
• get viewer's sponsor profile info, active goal
• get viewer's tiers

viewer is logged in user or api key owner.

{
  viewer {
    login
    ... on Sponsorable {
      sponsors(first: 100, orderBy: {field: RELEVANCE, direction: DESC}) {
        totalCount
        nodes {
          __typename
          ... on User {
            login
            name
            bio
            avatarUrl
            twitterUsername
            sponsorshipForViewerAsSponsorable {
              isActive
              createdAt
              tier {
                id
                name
                isOneTime
                monthlyPriceInDollars
              }
            }
          }
          ... on Organization {
            login
            name
            description
            avatarUrl
            twitterUsername
            sponsorshipForViewerAsSponsorable {
              isActive
              createdAt
              tier {
                id
                name
                isOneTime
                monthlyPriceInDollars
              }
            }
          }
        }
      }
    }
    sponsoring(first: 100) {
      nodes {
        __typename
        ... on User {
          login
          name
          bio
          avatarUrl
          twitterUsername
          sponsorshipForViewerAsSponsor {
            isOneTimePayment
            isActive
            createdAt
            tier {
              id
              isCustomAmount
              monthlyPriceInDollars
              isOneTime
              name
              description
            }
          }
        }
        ... on Organization {
          login
          name
          description
          avatarUrl
          twitterUsername
          sponsorshipForViewerAsSponsor {
            isOneTimePayment
            isActive
            createdAt
            tier {
              id
              isCustomAmount
              monthlyPriceInDollars
              isOneTime
              name
              description
            }
          }
        }
      }
    }
    sponsorsListing {
      url
      fullDescription
      activeGoal {
        kind
        description
        percentComplete
        targetValue
        title
      }
      tiers(first: 100) {
        nodes {
          id
          name
          isOneTime
          description
          monthlyPriceInDollars
          isCustomAmount
        }
      }
    }
  }
}

[needim]

I also used this query to design a page for my project.

You can check it out for inspiration: https://gider.im/sponsorship
The repository is here: https://github.com/needim/gider.im-website